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About This Book 


This book, Calls and Subroutines Reference: Base Operating System, provides information 
on application programming interfaces to the Advanced Interactive Executive Operating 
System (referred to in this text as AIX) for use on the IBM RISC System/6000 System. This 
book is part of AlX Calls and Subroutines Reference for IBM RISC System/6000, 
$C23-—2198, which is divided into the following four major sections: 


e Volumes 1 and 2, Calls and Subroutines Reference: Base Operating System, contains 
reference information about the system calls, subroutines, functions, macros, and 
statements associated with AIX base operating system runtime services, communications 
services, and devices services. 


e Volumes 3 and 4, Calls and Subroutines Reference: User Interface, contain reference 
information about the AlXwindows widget classes, subroutines, and resource sets; the 
AlXwindows Desktop resource sets; the Enhanced X-Windows subroutines, macros, 
protocols, extensions, and events; the X—Window toolkit subroutines and macros; and the 
curses and extended curses subroutine libraries. 


e Volume 5, Calls and Subroutines Reference: Kernel Reference, contains reference 
information about kernel services, device driver operations, file system operations 
subroutines, the configuration subsystem, the communications subsystem, the high 
function terminal (HFT) subsystem, the logical volume subsystem, the printer subsystem, 
and the SCS! subsystem. 


e Volumes 6, Calls and Subroutines Reference: Graphics, contains reference information 
and example programs for the Graphics Library (GL) and the AlXwindows Graphics 
Support Library (XGSL) subroutines. 


Who Should Use This Book 
This book is intended for experienced C programmers. To use this book effectively, you 
should be familiar with AIX or UNIX System V commands, system calls, subroutines, file 
formats, and special files. If you are not already familiar with the AIX operating system or the 
UNIX System V operating system, see AlX General Concepts and Procedures. 


How to Use This Book 


Overview of Contents 
This book contains the following alphabetically arranged sections consisting of system calls, 
subroutines, functions, macros and statements. In this book all system calls are described 
as subroutines. 


e Base Operating System Runtime (BOS) Services 
e Communications Services 

~ SNA Services 
AIX 3270 Host Connection Program (HCON) 
Remote Procedure Calls (RPC) 


Sockets 


Simple Network Management Protocol (SNMP) 


Network Computing System (NCS) 
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— Data Link Controls 
- X.25 Application 


Devices Services 


Highlighting 
The following highlighting conventions are used in this book: 
Bold Identifies commands, keywords, files, directories, and other items whose 
names are predefined by the system. 
Italics Identifies parameters whose actual names or values are to be supplied by 
the user. 


Monospace _ Identifies examples of specific data values, examples of text similar to what 


you might see displayed, examples of portions of program code similar to . 
what you might write as a programmer, messages from the system, or 
information you should actually type. 


Related Publications 
The following books contain information about or related to application programming 
interfaces: 


AIX General Programming Concepts for IBM RISC System/6000, Order Number 
$C23-2205. 


AIX Communication Programming Concepts for IBM RISC System/6000, Order Number 
$C23-2206. 


AIX Kernel Extensions and Device Support Programming Concepts for IBM RISC 
System/6000, Order Number SC23-—2207. 


AIX Files Reference for IBM RISC System/6000, Order Number SC23-2200. 
IBM RISC System/6000 Problem Solving Guide, Order Number SC23-2204. 


XL C Language Reference for IBM AIX Version 3 for RISC System/6000, Order Number 
SC09-1260. 


XL C User's Guide for IBM AIX Version 3 for RISC System/6000, Order Number 
SC09-1259. 


Ordering Additional Copies of This Book 
To order additional copies of this book, use Order Number SC23-2198. 
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2—2 Base Operating System Reference 


BREAK 


BREAK Statement 

Purpose 
Interrupts a loop in a LAF script. 

Syntax 
BREAK; 

Description 
The BREAK statement interrupts the execution of the innermost enclosing WHILE or 
REPEAT-UNTIL statement. Execution continues with the statement following the WHILE or 
REPEAT-—UNTIL statement. The BREAK statement is one of the script statements in the 
LAF language that are used to compose a LAF script. 

Example 


The statements below execute a loop. If a time out for the WAIT statement occurs, the 
BREAK statement terminates the repeat loop and executes the next statement: 


REPEAT 
DO 
MATCHAT(1,1,'VM/370?0ONLINE’ ); 
IF (NOT MATCH) DO /* if not found */ 
WAIT(2); /* wait for update to display or timeout */ 
IF (TIMEOUT) 
BREAK; 
END; 
END; 
UNTIL (MATCH); 


implementation Specifics 
The BREAK statement is part of the Logon Assist Feature of the AIX 3270 Host Connection 
Program/6000 (HCON). 


Related Information 
How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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cfxfer 


cfxfer Function 


Purpose 

Checks the status of the programmatic File Transfer. 
Library 

File Transfer Library (libfxfer.a) 
C Syntax 


#include <fxfer.h> 
cfxfer(sxfer) 


struct fxs “sxfer; 


Pascal Syntax 
%include fxfer.inc 
%include fxhfile.inc 


function pcfxfer(var sxfer : fxs) : integer; external; 


FORTRAN Syntax 
INTEGER FCFXFER 
EXTERNAL FCFXFER 
CHARACTER*XX SRC, DST, TIME 
INTEGER BYTCNT, STAT 
INTEGER ERRNO 


RC = FCFXFER (SAC, DST, BYTCNT, STAT, ERRNO, TIME, RC) 


Description 
The cfxfer function returns the status of the file transfer request made by the fxfer function. 
This function must be called once for each file transfer request. The cfxfer function places 
the status in the structure specified by the sxfer parameter for C and Pascal. For 
FORTRAN, status is placed in each corresponding parameter. 


Each individual file transfer and file transfer status completes the requests in the order the 
requests are made. If multiple asynchronous requests are made: 


e Toa single host session, the cfxfer function returns the status of each request in the 
same order the requests are made 


e To more than one host session, the cfxfer function returns the status of each request in 
the order it is completed. 


If the file transfer is run asynchronously and the cfxfer function is immediately called, the 
function returns a status not available (~2) code. An application performing a file transfer 
should not call the cfxfer function until an error (-1) or ready status (0) is returned. The 
application program can implement the status check in a FOR LOOP or a WHILE LOOP 
and wait for a—1 (negative one) or 0 (zero) to occur. 
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C Parameter 
sxfer 


Pascal Parameter 
Sfxfer 


cfxfer 


Specifies a record of type fxs defined in the fxfer.h file. 


The C struct fxs is defined as follows: 


struct fxs 


rm fxs _bytcnt; 
char “TSS. Srey 
char *fxs dst; 
char *fxs_ ctime; 
int fxs_stat; 
int fxs errno; 


]c.; 


Specifies a record of type fxs within the fxfer.inc file. 


The Pascal fxs record format is as follows: 


fxs = record 
fxs_bytcnt : integer; 
EXs sre > “stringper? 
fxs_dst : stringptr; 
fxs ctime : stringptr; 
fxs stat : integer; 
fxs errno : integer; 

end; 


C and Pascal fxs Field Descriptions 


fxc_bytent 


fxc_src 


fxc_dst 


fxs_ctime 


fxs_ stat 


fxs_errno 


Indicates the number of bytes transferred. 


Points to a static buffer containing the source file name. The static buffer is 
overwritten by each call. 


Points to a static buffer containing the destination file name. The static 
buffer is overwritten by each call. 


Specifies the time the destination file is created relative to Greenwich Mean 
Time (GMT), midnight on January 1, 1970. 


Specifies the status of the file transfer request. 


Specifies the error number that results from an error in a system call. 


FORTRAN Parameters 


SRC 
DST 


BYTCNT 
STAT 
ERRNO 
TIME 


Specifies a character array of XX length containing the source file name 


Specifies a character array of XX length containing the destination file 
name. 


Indicates the number of bytes transferred. 
Specifies the status of the file transfer request. 
Specifies the error number that results from an error in a system call 


Specifies the time the destination file is created. 
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cfxfer 


Return Value 
The cfxfer function returns the following: 


0 (zero), if status is available. 
—1, if an I/O error occurs on the fx_statxxxxxx status file and the status cannot be obtained 
—2, if status is not available or if there are no outstanding file transfer requests. 


The fx_statxxxxxx Status file contains the status of each file transfer request made by the 
application program. The fxfer function fills in the xxxxxx portion of the fx_stat file based on 
random letter generation and places the file in the $HOME directory. 


Implementation Specifics 
The cfxfer function is part of the AIX 3270 Host Connection Program/6000 (HCON). 


Files 
$HOME/fx_statxxxxxx Temporary file used for status 
/usr/lib/libfxfer.a Library containing C, FORTRAN, and Pascal interface 

file transfer functions. 

/usr/include/fxfer.h File transfer include file with structures and definitions. 
/usr/include/fxfer.inc Pascal file transfer include file with structure. 
/usr/include/fxconst.inc Pascal file transfer function constants. 
/usr/include/fxhfile.inc Pascal file transfer invocation include file. 


Related Information 
The fxfer command, fxfer function. 


HCON Overview for Programming, Understanding File Transfer Programming, File Transfer 
Program Interface Error Codes in Communications Programming Concepts. 
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DEBUG 


DEBUG Statement 


Purpose 
Enables debugging messages in a Logon Assist Feature (LAF) script. 
Syntax 
DEBUG; 
Description 


The DEBUG statement enables debugging messages in a LAF script. The DEBUG 
statement is one of the script statements in the LAF language that are used to compose a 
LAF script. The DEBUG statement operates on successive LAF statements. Debugging 
occurs up to the end of the LAF script or when a NODEBUG statement is encountered. The 
messages are written to the standard error. This statement should only be used in a script 
linked with the tlaf test program. If a script containing the DEBUG statement is linked with 
the file transfer program or an application using the HCON API, unpredictable results occur. 


implementation Specifics 
The DEBUG statement is part of the Logon Assist Feature of the AIX 3270 Host Connection 
Program/6000 (HCON). 


Related Information 
How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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DO-END 


DO-END Statement 
Purpose 
Groups Logon Assist Feature (LAF) statements. 
Syntax 
DO statementlist END; 
Description 
The DO—END statement is used for grouping LAF statements. The DO—-END statement is 
one of the script statements in the LAF language that are used to compose a LAF script. 
Expression 
statementlist A statement or statements to be executed that are grouped by a 
DO-END statement. 
Example 


The statements below search for CP READ string on line 24 of the terminal screen. The list 
waits for a screen update and then looks for the string. If the string cannot be found in two 
seconds, an exit is performed with a return code of 2. 


DO 
MATCH(24,1,’CP?READ’); 
IF (NOT MATCH) DO /* if not found */ 


WAIT(2); /* wait for update to display or timeout */ 
IF (TIMEOUT) 

EXIT(2); /* exit with error—can’t find it */ 
END; 


END; 


Implementation Specifics 
The DO~END statement is part of the Logon Assist Feature of the AIX 3270 Host 
Connection Program/6000 (HCON). 


Related Information 


How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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EXIT 


EXIT Statement 

Purpose 
Terminates the execution of a Logon Assist Feature (LAF) script. 

Syntax 
EXIT(numben; 

Description 
The EXIT statement halts the execution of a LAF script. The EXIT statement is one of the 
script statements in the LAF language that are used to compose a LAF script. Upon 
termination a specified return value is passed to the program that uses the LAF script. Ifa 
LAF script exits with a successful logon or logoff the return value is zero (0). The EXIT 
statement allows for abnormal exits whose return values indicate the area in the LAF script 
that failed. 

Expression 
number Specifies the return code value. 

Example 


This statement terminates the script with a return code of 3 if a time out occurs: 
IF(TIMEOUT) EXIT(3); 
Implementation Specifics 


The EXIT statement is part of the Logon Assist Feature of the AlX 3270 Host Connection 
Program/6000 (HCON). 


Related Information 
How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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FINISH 


FINISH Statement 


Purpose 

Ends a Logon Assist Feature (LAF) script. 
Syntax 

FINISH; 
Description 


The FINISH statement ends a LAF script. The FINISH statement is one of the script 
statements in the LAF language that are used to compose a LAF script. 


Each LAF script requires one FINISH statement, and it must be the last statement in the 
script. The FINISH statement implies that a zero (0) return value is passed back to the 
program using the LAF script (fxfer function or API functions). This return value denotes a 
successful logon or logoff. Any other return value is interpreted by the program using the 
LAF script as unsuccessful logon or logoff. 


Implementation Specifics 


The FINISH statement is part of the Logon Assist Feature of the AIX 3270 Host Connection 
Program/6000 (HCON). 


Related Information 
The EXIT statement. 


How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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fxfer Function 


Purpose 
Library 


C Syntax 


Initiates a file transfer from within a program executing in AIX. 


File Transfer Library (libfxfer.a) 


#include <fxfer.h> 
fxfer (xfer, sessionname) 
struct fxe *xfer, 

char *sessionname; 


Pascal Syntax 


%include /usr/include/fxfer.inc 
%include /usr/include/fxhfile.inc 
%include /usr/include/fxconst.inc 
function pfxfer 

(var xfer: fxc; sessionname : stringpth : 
integer; external; 


FORTRAN Syntax 


INTEGER FFXFER 

EXTERNAL FFXFER 

CHARACTER*XX SACF, DSTF, LOGID, SESSIONNAME 
INT FLAGS, RECL, BLKSIZE, SPACE, INCR, UNIT, RC 


RC = FFxfer (SRCF, DSTF, LOGID, FLAGS, RECL, BLKSIZE, SPACE, 


+ INCR, UNIT, SESSIONNAME) 


Description 
The fxfer function transfers a file from a specified source to a specified destination. The file 


transfer is accomplished as follows: 


fxfer 


e Inthe C or Pascal language, the fxfer or pfxfer function transfers a file specified by the 
fxc_src variable to the file specified by the fxc_dst variable. Both variables are defined in 


the fxce structure. 


e Inthe FORTRAN language, the FFxfer function transfers a file specified by the SRCF 


variable to the file specified by the DSTF variable. 


The file names are character strings. The RISC System/6000 file names must be in AIX 
format. The host file names must conform to the host naming convention, which must be 


one of the following formats: 


VM/CMS: filename filetype filemode 


MVS/TSO: data_set_name [(member_name)][/password] 


C Parameters 
xfer Specifies a pointer to the fxe structure defined in the fxfer.h 


file. 
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fxfer 


sessionname 


Pascal Parameters 
xfer 


sessionname 


FORTRAN Parameters 
SRCF 


DSTF 


LOGID 


SESSIONAME 


FLAGS 
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Points to the name of a session, specifying the host 
connectivity to be used by the File Transfer Programming 
Interface. The session name is a single character in the range 
of a~z. Capital letters are interpreted as lowercase letters. 
Session variables are defined in a HCON session profile. If 
the sessionname is set to NULL the fxfer function assumes 
you are running in an e789 subshell. 


Specifies a record of type fxe within the fxfer.ince file. 


Points to the name of a session. The sessionname defines 
the host connectivity to be used by the File Transfer 
Programming Interface. The session name is a single 
character in the range of a—z. Capital letters are interpreted 
as lowercase letters. Session variables are defined in a 
HCON session profile. If the sessionname is set to char(0) the 
pfxfer function assumes you are running in an e789 subshell. 


Specifies a character array of XX length containing the source 
file name. 


Specifies a character array of XX length containing the 
destination file name. 


Specifies a character array of XX length containing the logon 
ID. 


Points to the name of a session. The sessionname defines 
the host connectivity to be used by the File Transfer 
Programming Interface. The session name is a single 
character in the range of a—z. Capital letters are interpreted 
as lowercase letters. Session variables are defined in a 
HCON session profile. If the SESS/IONNAME is set to char(0) 
the FF xfer function assumes you are running in an e789 
subshell. 


Contains the option flags value, which is the sum of the 
desired option values listed below: 


1 Upload 

2 Download 

4 Translate On 

8 Translate Carriage Return Line Feed 
16 Replace 

32 Append 

64 Queue 

128 Fixed Length Records 


fxfer 


256 Variable Length Records 
512 Undefined Length (TSO only) 
1024 Host System TSO 
2048 Host System CMS 

RECL Specifies the logical record length. 

BLKSIZE Specifies the block size. 

SPACE Specifies the allocation space. 

INCR Specifies the allocation space increment. 

UNIT Specifies the unit of allocation, which is: 
-1 Specifies the number of TRACKS 
-2 Specifies the number of CYLINDERS 


Note: All FORTRAN character array strings must be NULL-terminated. For example: 


SRCF = ‘rtfile’//CHAR(0) 


A positive number indicates the number of bytes to be allocated. 


Return Value 


If the fxfer function is called synchronously, it returns the value zero (0) when the transfer is 
completed. The application program can then issue a cfxfer function call to obtain the status 
of the file transfer. 


If the fxfer function is called asynchronously, it returns zero (0) immediately. The 
application program can issue a cfxfer function call to determine when the file transfer is 
completed and to obtain the status of the file transfer. If the status cannot be reported by the 
cfxfer function due to an I/O error on the fx_statxxxxxx status file, the cfxfer function 
returns a —1 (negative one). If the status is not ready, the cfxfer function returns a —2 
(negative two). 


The fx_statxxxxxx status file contains the status of each file transfer request made by the 
application program. The fxfer function fills in the xxxxxx portion of the fx_stat file based on 
random letter generation and places the file in the $HOME directory. 


Implementation Specifics 
The fxfer function is part of the AIX 3270 Host Connection Program/6000 (HCON). 


The fxfer function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter plus appropriate cables for attachment to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter plus appropriate cables for attachment to an IBM 
5088 Graphics Control Unit. 


This function requires one of the following IBM System/370 operating system environments 
be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, or MVS/XA 
TSO/E. 
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txfer 


Files 


This function requires that the System/370 IBM Host—Supported File Transfer Program 
(IND$FILE) be installed on the System/370. 


This function is not available for Japanese Language Support. 


$HOME/fx_statxxxxxx Temporary file used for status 

/usr/lib/Aibfxfer.a Library containing C, FORTRAN, and Pascal interface 
file transfer functions. 

/usr/include/fxfer.h File transfer include file with structures and definitions. 

/usr/include/fxfer.inc Pascal file transfer include file with structure. 

/usr/include/fxconst.inc Pascal file transfer function constants. 

/usr/include/fxhfile.inc Pascal file transfer invocation include file. 


Related Information 
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The file transfer check status function is the cfxfer function. 


HCON Overview for Programming, Understanding the File Transfer Program Interface, How 


to Compile a File Transfer Program, File Transfer Program Interface Error Codes in 
Communications Programming Concepts. 


Base Operating System Reference 


G32ALLOC 


G32ALLOC Function 


Purpose 
Starts interaction with an AIX API application running simultaneously on the RISC 
System/6000. 

Syntax 
G32ALLOC 

Description 


The G32ALLOC function starts a session with an AIX API application by sending a message 
to the AIX g32_alloc system call indicating that the allocation is complete. The GB2ALLOC 
function is a HCON API function that can be called by a 370 Assembler applications 
program. 


Return Values 
This call sets register 0 (zero), to the following values: 


>= 0 Normal return; successful call. The value returned indicates the maximum 
number of bytes that may be transferred to an AIX application via 
G32WRITE or received from an AIX application via GB2READ. 


Example 
The following 370 Assembler code example illustrates the use of the host GZ2ALLOC 
function: 


L R11,=v(G32DATA) 
USING G32DATAD,R11 


G32ALLOC /* Allocate a session */ 
LTR RO,RO 

BNM OK /* Normal completion */ 
C RO,G32ESESS /*Session error */ 

BE SESSERR 

C RO,G32ESYS /* System error */ 


BE SYSERR 


Implementation Specifics 
The G32ALLOC function is part of the AIX 3270 Host Connection Program/6000 (HCON). 


The G32ALLOC function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 
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G32ALLOC 


The G32ALLOC function requires one of the following IBM System/370 operating system 


environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The G32ALLOC function is not available for Japanese Language Support. 


Related Information 
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Additional host interface functions are the G32DLLOC function, G32READ function, and 
G32WRITE function. 


AIX session control subroutines are the g32_alloc subroutine, g32_close subroutine, 
g32_dealloc subroutine, g32_open subroutine, and g32_openx subroutine. 


AIX message interface subroutines are the g32_get_status subroutine, g32_read 
subroutine, and g32_write subroutine. 


HCON Overview for Programming, Understanding the HCON Application Programming 


Interfaces, Understanding the HCON Host Interface in Communications Programming 
Concepts. 


How to Compile a Host HCON API Program, Host API Errors, Sample Flows of API 
Programs in Communications Programming Concepts. 
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g32_alloc 


g32_alloc Function 


Purpose 


Library 


C Syntax 


Initiate interaction with a host application. 


HCON Library 

C (libg3270.a) 

Pascal (libg3270p.a) 
FORTRAN (libg3270f.a) 


#include <g32_api.h> 
g32_alloc (as, app/iname, mode) 
struct g32_api “as; 

char *appiname; 

int mode; 


Pascal Syntax 


function g32alle(var as : g32_api; 
appliname : stringptr; 
mode : integer): integer; external; 


FORTRAN Syntax 


EXTERNAL G32ALLOC 
INTEGER RC, MODE, AS(9), G32ALLOC 
CHARACTER* XX NAME 


RC = G32ALLOC (AS, NAME, MODE) 


Description 


The g32_alloc function initiates interaction with a host application and sets the API mode. 
The host application program is invoked by entering its name, using the logical terminal 
interface. 


If invocation of the host program is successful and the mode is API/API, control of the 
session is passed to the AIX application. If the mode is API/3270, the emulator retains 
control of the session. The application communicates with the session by way of the logical 
terminal interface. 


The g32_alloc function may be used only after a successful open using the g32_open or 
g32_openx function. The g32_alloc function must be issued before using any of the 
message or logical terminal interface functions. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 
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g32_alloc 


C Parameters 


as 


appiname 


mode 


Pascal Parameters 


as 


appiname 


sessionmode 


Specifies a pointer to a g32_api structure. Status information is 
returned in this structure. . 


Specifies a pointer to the name of the host application that is to be 
executed. This string should be the entire string necessary to start 
the application, including any necessary parameters or options. 
When using API/3270 mode, place the value in two double quotes 
(““Testload””) or specify a null string (“”). When using API/API 
mode, place the host application name in double quotes ("Testload”) 


Specifies the API mode.The types of modes that can be used are 
contained in the g32_api-h file and are defined as follows: 


MODE_ 3270 
The API/3270 mode is for communicating with host 
applications that assume they are communicating with a 
3270terminal. Applications in this mode use the logical 
terminal interface to communicate with the host application. In 
API/3270 mode, if appiname is a null pointer, no host 
application is started. 


MODE_API 
The API/API mode is for communicating with host applications 
that assume they are communicating with a program. 
Applications in this mode use the message interface to 
communicate with host applications using the host API. 


Note: When a session is in this mode, all activity to the 
screen is stopped until this mode is exited. API/3270 
mode functions cannot be used while in the API/API 
mode. 


MODE_API_T 
The API_T mode is the same as MODE_API except this mode 
translates messages received from the host from EBCDIC to 
ASCIl, and translates messages sent to the host from ASCII to 
EBCDIC. The translation table used is determined by the 
country field in the HCON session profile. 


Note: A host application started in API/API or API/API_T 
mode must issue a G32ALLOC function as the API 
waits for an acknowledgment from the host application, 
when starting an API/API mode session. 


Specifies the g32_api structure. 


Specifies a stringptr containing the name of the host application to 
be executed. This string should be the entire string necessary to 
Start the host application, including any necessary parameters and 
options. A NULL application name is valid in 3270 mode. 


Specifies the mode desired for the session. 
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g32_alloc 


FORTRAN Parameters 


AS Specifies the g32_api equivalent structure as an array of integers. 
NAME Specifies the name of the application that is to execute on the host. 
MODE Specifies the desired mode for the API. 


Return Values 
Upon successful completion: 


e A value of 0 is returned. 

Upon unsuccessful completion: 

e Avalue of —1 is returned. 

e The errcode bit is set to an error code identifying the error. 


e The xerrinfo bit can be set to give more information about the error. 


Example 
C Language 
1. The following example illustrates the use of the g32_alloc function: 
#include <g32_api.h /* API include file */ 
main () 
{ 
struct g32 api *as, asx;  /* asx is statically defined*/ 
int session_mode = MODE API /* api session mode. Other modes 
are MODE API T */ 
char appl_name [20] /* name of the application to 
run on the host*/ 
int return; /* return code */ 
strcepy (appl _name, “APITESTN”); /* name of host application*/ 
return = g32 alloc(as, appl _ name, session_mode); 


return = g32 dealloc(as); 


Implementation Specifics 
The g32_alloc function is part of the AIX 3270 Host Connection Program/6000 (HCON). 


The g32_alloc function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (nNon—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 
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g32_alloc 


Files 


The g32_alloc function requires one of the following IBM System/370 operating system 


environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The g32_alloc function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/usr/include/g32const.inc Defines Pascal API constants 

/usr/include/g32hfile.inc Defines Pascal API external definitions 

/usr/include/g32types.inc Defines Pascal API data types 


Related Information 


Additional session control functions are the g32_close function, g32_dealloc function, 
g32_open function, and g32_openx function. 


AIX logical terminal interface functions are the g32_get_cursor function, g32_get_data 
function, g32_notify function, g32_search function, and g32_send_keys function. 


The API file transfer functions is the g32_fxfer function. 


AIX message interface functions are the g32_get_status function, g32_read function, and 
g32_write function. 


Host interface functions are the GB2ALLOC function, GZ2DLLOC function, GJ2READ 
function, and G32WRITE function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interface, Understanding the AIX Interface for HCON API, API error codes, Sample Flows of 
API Programs in Communications Programming Concepts. 


Understanding HCON Emulator Session Profiles in Communication Concepts and 
Procedures. 
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g32_close 


g32_close Function 


Purpose 

Detaches from a session. 
Library 

HCON Library 

C (libg3270.a) 

Pascal (libg3270p.a 

FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 


g32_close(as) 
struct g32_api *as; 


Pascal Syntax 
function g32clse (var as : g32_api) : integer; external; 


FORTRAN Syntax 
EXTERNAL G32CLOSE 
INTEGER AS(9), G32CLOSE 


RC = G32CLOSE(AS) 


Description 
The g32_close function relinquishes use of the session. If the g32_open or g32_openx 
created the session, the g32_close function will log off from the host and terminate the 
session. Any session must be terminated (by using the g32_dealloc function) before 
issuing the g32_close function. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 


C Parameter 


as Specifies a pointer to a g32_api structure. Status is returned in this 
structure. 


Pascal Parameter 


as Specifies a g32_api structure. 
FORTRAN Parameter 
AS Specifies the g32_api equivalent structure as an array of integers. 
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g32_close 


Return Values 
Upon successful completion: 


Examples 
C Language 


e Avalue of 0 is returned. 


Upon unsuccessful completion: 


e A value of —1 is returned. 


e The errcode bit is set to an error code identifying the error. 


e The xerrinfo bit can be set to give more information about the error. 


1. 


The following example fragment illustrates the use of the g32_close function: 


#include <g32_api.h> /* API include file */ 
main() 

{ 

struct g32_api *as; /* g32 structure */ 


int return; 


return = g32 close(as); 


Implementation Specifics 
The g32_close function is part of the AIX 3270 Host Connection Program/6000 (HCON). 


Files 


The g32_close function requires one of the following network communication adapters: 


IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. . | 


IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_close function requires one of the following IBM System/370 operating system 


environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The g32_close function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/usr/include/g32const.inc Defines Pascal API constants 

/usr/include/g32hfile.inc Defines Pascal API external definitions 

/usr/include/g32types.inc Defines Pascal API data types 
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g32_close 


Related Information 
Additional session control functions are the g32_alloc function, g32_dealloc function 
g32_open function, and g32_openx function. 


AIX logical terminal interface functions are the g32_get_cursor function, g32_get_data 
function, g32_notify function, g32_search function, and g32_send_keys function. 


The API file transfer functions is the g32_fxfer function. 


AIX message interface functions are the g32_get_status function, g32_read function, and 
g32_write function. 


Host interface functions are the G32ALLOC function, G32DLLOC function, GJ2READ 
function, and G32WRITE function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the AIX Interface for HCON API, API error codes, Sample Flows 
of API Programs in Communications Programming Concepts. 


AIX 3270 Host Connection Program (HCON) 2-23 


g32_dealloc 


g32_dealloc Function: 


Purpose 

Ends interaction with a host application. 
Library 

HCON Library 

C (libg3270.a) 

Pascal (libg3270p.a 

FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 


g32_dealloc(as) 
struct g32_api *as; 


Pascal Syntax 
function g32deal (var as : g32_api) : integer; external; 


FORTRAN Syntax 


EXTERNAL G32DEALLOC 
INTEGER AS(9), G32DEALLOC 


RC = G32DEALLOC(AS) 
Description 


The g32_dealloc function ends interaction with the AIX application and the host application. 
The function releases control of the session. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 


C Parameter 
as Specifies a pointer to a g32_api structure as an array of integers. 


Pascal Parameter 


as Specifies the g32_api structure. 
FORTRAN Parameters 
AS Specifies the g32_api equivalent structure. 


Return Values 
Upon successful completion: 


e The session is terminated. 


e Avalue of 0 is returned. 
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Examples 


g32_dealloc 


Upon unsuccessful completion: 


C Language 


implement 


Files 


A value of —1 is returned. 
The errcode bit is set to an error code identifying the error. 


The xerrinfo bit can be set to give more information about the error. 


. The following example illustrates the use of the g32_dealloc function: 

#include <g32_api.h> /* API include file */ 

main () 

{ 

struct g32_api *as, asx; /* asx is statically defined */ 

int session_mode = MODE APT; /* api session mode. Other modes 
are MODE API T */ 

char appl_name [20]; /* name of the application to 
run on the host ay f 

int return; /* return code * / 


strcepy (appl _ name, “APITESTN”); /* name of host application */ 
return = g32 alloc(as, appl_name, session_mode); 


return = g32_ dealloc(as); 


ation Specifics 
The g32_dealloc function is part of the AIX 3270 Host Connection Program/6000 (HCON). 


The g32_dealloc function requires one of the following network communication adapters: 


IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 


Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 


DFT) mode. 


IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_dealloc function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The g32_dealloc function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 
/usr/include/g32const.inc Defines Pascal API constants 


AIX 3270 Host Connection Program (HCON) 2-25 


g32_dealloc 


/usr/include/g32hfile.inc Defines Pascal API external definitions 
/usr/include/g32types.inc Defines Pascal AP! data types 


Related Information 
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Additional session control functions are the g32_alloc function, g32_close function, 
g32_open function, and g32_openx function. 


AIX logical terminal interface functions are the g32_get_cursor function, g32_get_data 
function, g32_notify function, g32_search function, and g32_send_keys function. 


The API file transfer functions is the g32_fxfer function. 


AIX message interface functions are the g32_get_status function, g32_read function, and 
g32_write function. 


Host interface functions are the G32ALLOC function, GZ2DLLOC function, GJ2READ 
function, and G32WRITE function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the AIX Interface for HCON API, API error codes, Sample Flows 
of API Programs in Communications Programming Concepts. 
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G32DLLOC 


G32DLLOC Funetion 


Purpose 
Terminates interaction with an AIX API application running simultaneously on the RISC 
System/6000. 

Syntax 
G32DLLOC 

Description 


The G32DLLOC function ends interaction with an AIX API application. The G32DLLOC 
function is a HCON API function that can be called by a 370 Assembler applications 
program. 


Return Values 
This call sets register 0 (zero) to the following values: 
0 Zero. A normal return; call successful 
<0 Less than zero. Error condition. 
Examples 


The following 370 Assembler code example illustrates the use of the host GZ2DLLOC 
function: 


L R11l,=v(G32DATA) 
USING G32DATAD,R11 


G32DLLOC /* Deallocate a session */ 
C RO, G32ESESS /* Check for G32 error rf 

BE SESSERR /* Branch if error * / 
C RO, G32ESYS /* Check for system error */ 
BE SYSERR /* Branch if error * / 


Implementation Specifics 
The G32DLLOC function is part of the AIX 3270 Host Connection Program/6000 (HCON). 


The G32DLLOC function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The G32DLLOC function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The G32DLLOC function is not available for Japanese Language Support. 
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G32DLLOC 


Related Information 
Additional host interface functions are the G32ALLOC function, G32READ function, and 
G32WRITE function. 


AIX session contro! subroutines are the g32_alloc subroutine, g32_close subroutine, 
g32_dealloc subroutine, g32_open subroutine, and g32_openx subroutine. 


AIX message interface subroutines are the g32_get_status subroutine, g32_read 
subroutine, and g32_write subroutine. 
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g32_fxfer 


g32_fxfer Function 


Purpose 


Library 


C Syntax 


Invokes a file transfer. 


HCON Library 


File Transfer Library (libfxfer.a) 
C (libg3270.a) | 

Pascal (libg3270p.a) 

Fortran (libg3270f.a) 


#include <g32_api.h> 
#include <fxfer.h> 


g32_fxfer(AS, Xfer) 
struct g32_api *AS; 
struct fxce *Xfer, 


Pascal Syntax 


const 

%include /usr/include/g32const.inc 
%include /usr/include/g32fxconst.inc 
type 

%include /usr/include/g32types.inc 
%include /usr/include/fxhfile.inc 


function g32fxfer(var AS :g32_api; var Xfer : fxc) : integer; external; 


FORTRAN Syntax 


INTEGER G32FXFER, RC, AS(9) 

EXTERNAL G32FXFER 

CHARACTER*XX SACF, DSTF 

INTEGER FLAGS,RECL,BLKSIZE,SPACE,INCR,UNIT 


RC = G32FXFER(AS, SCRE DSTF FLAGS, RECL,BLKSIZE, SPACE, 
+ INCR,UNIT) 


Description 


The g32_fxfer function allows a file transfer to take place within an API program without the 
API program having to invoke a g32_close and relinquish the link. The file transfer is run 
programmatically, meaning the user must set up the flag options, the source file name, and 
the destination file name using either the programmatic fxfer fxe structure for C and Pascal 
or the numerous variables for FORTRAN. The g32_fxfer function will in affect detach from 
the session without terminating it, run the specified file transfer and then reattach to the 
session. 


If a g32_alloc has been issued before invoking the g32_fxfer command, be sure that the 
corresponding g32_dealloc is incorporated into the program before the g32_fxfer function 
is called. 
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g32_fxfer 


The status of the file transfer can be checked by using the cfxfer file transfer status check 
function after the g32_fxfer function has been invoked. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 


C Parameters 


AS Specifies a pointer to the g32_api structure. Status is returned in this 
structure. 
Xfer Specifies a pointer to the fxc structure defined in the fxfer.h file. 


Pascal Parameters 


AS Specifies a record of type g32_api. 
Xfer Specifies a record of type fxc within the fxfer.ince file. 
FORTRAN Parameters 
AS Specifies the g32_api equivalent structure as an array of integers. 
SRCF Specifies a character array of XX length containing the source file name. 
DSTF Specifies a character array of XX length containing the destination file 
name. 
FLAGS Contains the option flags value, which is the sum of the desired option 
values listed below: 
1 Upload 
2 Download 
4 Translate On 
8 Translate Carriage Return Line Feed 
16 Replace 
32 Append 
64 Queue — this option may be specified by the user, but it is 
blocked by the G32FXFER command 
128 Fixed Length Records 
256 Variable Length Records 
512 Undefined Length (TSO only) 
1024 Host System TSO 
2048 Host System CMS 
RECL Specifies the logical record length. 
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Return Values 


Examples 


g32_fxfer 


BLKSIZE Specifies the block size. (TSO only) 
SPACE Specifies the allocation space. (TSO only) 
INCR Specifies the allocation space increment. (TSO only) 
UNIT Specifies the unit of allocation (TSO only), which is: 
-1 is the number of TRACKS 
-2 is the number of CYLINDERS 


A positive number indicates the number of bytes to be allocated. 


Note: All FORTRAN character array strings must be NULL—terminated (for 


example, SRCF = rtfile//CHAR(0)). 


Upon successful completion: 


0 The user may call the cfxfer function to get the status of the 
file transfer. 


Upon unsuccessful completion: 


1 The file transfer did not complete successfully. The user 
may Call the cfxfer function to get the status of the file 
transfer. 


—1 The g32_fxfer command failed while accessing the link. 
The errcode bit is set to an error code identifying the error. 
The xerrinfo bit can be set to give more information about 
the error. 


1.C 
#include <g32_api.h> /* API include file */ 
#include <fxfer.h> /* file transfer include file */ 
main() 
{ 


struct g32_api *as,asx; 

struct fxc *xfer; 

struct fxs sxfer; 

int session_mode=MODE_ 3270; 

char *aixfile="/etc/motd”;: 

char *hostfile="test file a”; 

char sessionname[30],uid[30],pw[30]; 

int mlog=0,ret=0; 

as = &asx; 

sessionname = ‘\0’; /* We are assuming SNAME is set */ 


ret=g32_open(as,mlog,uid,pw,sessionname) ; 
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g32_fxfer 
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} 


printf("The g32_ open return code = %d\n"”,ret); 


/* Malloc space for the file transfer structure */ 
xfer = (struct fxc *) malloc(2048); 
/* Set the file transfer flags to upload, 
replace, translate and Host CMS */ 
xfer—>fxc_opts.f flags = FXC_UP | FXC_REPL | FXC_TNL | FXC_CMS; 
xfer—>fxc_opts.f_lrecl = 80; /* Set the Logical Record length 


to 80 */ 
xfer—>fxc_sre = aixfile; /* Set the Source file name to 
aixfile */ 
xfer—>fxc_dst = hostfile; /* Set the Destination file name 


to hostfile */ 
ret=g32 fxfer(as,xfer); 
printf("The g32_ fxfer return code = %d\n"”,ret); 


/* If the file transfer completed then get the status code of 
the file transfer */ . 


if ((ret == 0) || (ret == 1)) { 
ret = cfxfer(&sxfer); 
if (ret == 0) { 
printf(”Source file: s\n",sxfer.fxs_src); 
printf("Destination file: s\n”,sxfer.fxs_dst); 
printf(”Byte Count: d\n”,sxfer.fxs_bytcnt); 


printf(”"Status Message Number: %d\n”",sxfer.fxs_stat); 


( 
printf("File transfer time: d\n",sxfer.fxs_ctime) ; 
( 
printf(”System Call error number: %d\n",sxfer.fxs_errno); 


ret=g32_ close(as); 
printf("”The g32_ close return code = %d\n”,ret); 
return(0); 


. Pascal: 


program testl(input,output); 

const 

Sinclude /usr/include/g32const.ine 
include /usr/include/fxconst.inc 

type 

Sinclude /usr/include/g32hfile.inc 
Sinclude /usr/include/g32types.inc 
include /usr/include/fxhfile.inc 

var 


as:g32 api; 

xfer:fxc; 

sxfer:fxs; 
ret,sess_mode,flag:integer; 
session,timeout,uid,pw:stringptr; 
source,destination:stringptr; 


begin 


sess_mode = MODE _3270; 
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flag := 0; 

{* Initialize API stringptrs and create space *} 
new(uid,8); 

uid@ := chr(0); 

new(pw,8); 

pw@ := chr(0); 

new(session,2); 


session@ := ’a’; {* Open session a *} 
new(timout,8); 
timeout := '60’; 


{* Call g320penx and open session a *} 
ret := g320penx(as,flag,uid,pw,session,timeout); 
writeln(’The g320penx return code = ’',ret:4); 


{* Set up the file transfer options and file names *} 
new(source,1024); 
source := ‘'testfile’; {* Source file, assumes testfile exists 
in the current directory *} 
new(destination,1024); 
destination := ‘testfile’; {* Destination file, TSO file 
testfile *} 
{* Set flags to Upload, Replace, Translate and Host TSO *} 
xfer.fxc_opts.f flags := FXC_UP + FXC_TSO + FXC_REPL + FXC_TNL; 
xfer.fxc_srce := source; 
xfer.fxc_dst := destination; 
{* Call the g32_fxfer using the specified flags and file names 
* 
} 
ret := g32fxfer(as,xfer); 
writeln(’The g32fxfer return code = ',ret:4); 
{* If g32_fxfer returned with 1 or 0 call the file transfer 
status check function *} 
if (ret >= 0) then begin 
ret := pcfxfer(sxfer); 
if (ret = 0) then begin 


writeln(’Source file: ',sxfer.fxs_src@); 
writeln(’Destination file: ',sxfer.fxs_dst@); 
writeln(’File Transfer Time: ',sxfer.fxs_ctime®@) ; 
writeln(’Byte Count: ’,sxfer.fxs_bytcnt); 
writeln(’Status Message Number: ',sxfer.fxs_stat); 
writeln('System Call Error Number: ',sxfer.fxs_errno); 
end; 


end; 


{* Close the session using the g32close function *} 
ret := g32close(as); 

writeln(’The g32close return code = ',ret:4); 

end. 
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3. FORTRAN: 


INTEGER G320PENX,G32FXFER,G32CLOSE,FCFXFER 
INTEGER RET,AS(9)FLAG 

EXTERNAL G320PENX 

EXTERNAL G32FXFER 

EXTERNAL G32CLOSE 

EXTERNAL FCFXFER 

CHARACTER*8 UID 

CHARACTER*8 PW 

CHARACTER*2 SESSION 

CHARACTER*8 TIMEOUT 

CHARACTER*256 SRCF 

CHARACTER*256 DSTF 

CHARACTER*256 SRC 

CHARACTER*256 DST 

CHARACTER*40 TIME 

INTEGER BYTCNT,STAT,ERRNO, TIME 

INTEGER FLAGS,RECL, BLKSIZE,SPACE,INCR,UNIT 


Cc Set up all FORMAT statement 
1 FORMAT(”THE G320PENX RETURN CODE = ",T4) 
2 FORMAT(”THE G32FXFER RETURN CODE = "”,14) 
3 FORMAT(”THE G32CLOSE RETURN CODE = ”,T14) 
4 FORMAT(”THE FCFXFER RETURN CODE = "”,14) 
5 FORMAT (?°—————_$_____________—_______" ) 
10 FORMAT(”SOURCE FILE: "”,A) 
11 FORMAT("”DESTINATION FILE: ”,A) 
12 FORMAT("BYTE COUNT: ”,110) 
13 FORMAT("TIME: ",A) 
14 FORMAT(”STATUS MESSAGE NUMBER: ”,110) 
15 FORMAT(”SYSTEM CALL ERROR NUMBER: "”,110) 
c Set up all character values for the G320PENX command 
UID = CHAR(0) 
PW = CHAR(0) 
SESSION = 'z'//CHAR(0) 
TIMEOUT = '’60’//CHAR(0) 
FLAG = 0 
SRCF = ‘testcasel’//CHAR(0) 
DSTF = ’/u/test.casel’//CHAR(0) 
Cc Source and Destination files for the fcfxfer status check 
command 
SRC = CHAR(0) 
DST = CHAR(0) 
C Set the G32FXFER file transfer flags and options 
Cc Take the defaults for Logical Record Length, Block Size, 
and Space 
RECL = 0 
BLKSIZE = 0 
SPACE = 0 
C Set FLAGS to download (2), translate(4), and Host 
TSO(1024) 
FLAGS = 1030 
c Call G320PENX 


RET = G320PENX(AS,FLAG, UID, PW, sessionname, TIMEOUT) 
WRITE(*,1) RET 
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C Call G32FXFER 
RET = G32FXFER(AS,SRCF,DSTF, FLAGS, RECL, BLKSIZE, SPACE 
+ INCR,UNIT) 
WRITE(*,2) RET 


Cc Call G32CLOSE 
RET = G32CLOSE(AS) 
WRITE(*,3) RET 
Cc Call FCFXFER for file transfer status output 


RET = FCFXFER(SRC,DST,BYTCNT, STAT, ERRNO, TIME) 
WRITE(*,4) RET 
WRITE(*,5) 
WRITE(*,10) SRC 
WRITE(*,11) DST 
WRITE(*,12) BYTCNT 
WRITE(*,13) TIME 
WRITE(*,14) STAT 
WRITE(*,15) ERRNO 
WRITE(*,5) 

STOP 

END 


Implementation Specifics 


Files 


The g32_fxfer function is part of the AIX 3270 Host Connection Program/6000 (HCON). 
The g32_fxfer function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter plus appropriate cables for attachment to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—-SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter plus appropriate cables for attachment to an IBM 
5088 Graphics Control Unit. 


This function requires one of the following IBM System/370 operating system environments 
be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, or MVS/XA 
TSO/E. 


This function requires that the System/370 IBM Host—Supported File Transfer Program 
(IND$FILE) be installed on the System/370. 


This function is not available for Japanese Language Support. 


/usr/include/fxfer.h File transfer include file with structures and definitions for 
C. 

/usr/include/fxconst.inc Pascal fxfer function constants. 

/usr/include/fxhfile.inc Pascal file transfer invocation include file. 

/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 
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/usr/include/g32const.inc Defines Pascal API constants 
/usr/include/g32hfile.inc Defines Pascal AP! external definitions 
/usr/include/g32types.inc Defines Pascal API data types 


Related Information 
Session control functions are the g32_open function, the g32_openx function, the 
g32_close function, the g32_alloc function, and the g32_dealloc function. 


The fxfer function and cfxfer function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the AIX Interface for HCON API, API error codes, Sample Flows 
of API Programs in Communications Programming Concepts. 
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g32_get_cursor Function 


Purpose 
Sets the row and column components of the g32_api structure to the current cursor position 
in a presentation space. 
Library 
HCON Library 
C (libg3270.a) 
Pascal (libg3270p.a) 
FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 


g32_get_cursor(as) 
struct g32_api as 


Pascal Syntax 
function g32curs (var as : g32_api) : integer; external; 


FORTRAN Syntax 
EXTERNAL G32GETCURSOR 
INTEGER AS(9), G32GETCURSOR 


RC = G32GETCURSOR(AS) 


Description 
The g32_get_cursor function obtains the row and column address of the cursor and places 


these values in the as structure. An application can only use the g32_get_cursor function 
in API/3270 mode. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 


C Parameter 


as Specifies a pointer to the g32_api structure. The row (row) and column (column) 
address of the cursor is set here. Status information is also set in this structure. 


Pascal Parameter 
as Specifies the g32_api structure. 


FORTRAN Parameter 


AS Specifies the g32_api equivalent structure as an array of integers. 
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Return Values 
Upon successful completion: 


e A value of 0 is returned. 


e The corresponding row element of the as structure is the row position of the beginning of 


the matched string. 


e The corresponding column element of the as structure is the column position of the 


beginning of the matched string. 


Upon unsuccessful completion: 


Examples 
C Language 
, 


An error code (—1 (—one)) is returned. 
The errcode bit is set to the error code identifying the error. 


The xerrinfo bit can be set to give more information about the error. 


. The following example fragment illustrates the use of the g32_get_cursor function in an 


api_3270 mode program: 


Note: The following example is missing the required g32_open and g32_alloc 
functions which are necessary for every HCON Workstation AP! program. 


#include <g32_api.h> /* API include file */ 

main() 

{ 

struct g32_api *as; /* g32 structure */ 

char *buffer; /* pointer to char string 
*/ 

int return; /* return code */ 

char *malloc(); /* C memory allocation 


function */ 


e 
° 


return = g32_notify(as,1); /* Turn notification on */ 
buffer = malloc(10); 

return = g32_get_cursor(as); /* get location of cursor */ 
printf (” The cursor positionis row: $d col: %d/n”; 


as —> row, as —> column); 
/* Get data from host starting at the current row and column */ 
as —> length = 10; /* length of a pattern on host */ 
return = g32_get_data(as,buffer); /* get data from host */ 
printf(“The data returned is <%s>\n"”,buffer); 


/* Try to search for a particular pattern on host */ 
as —>row =1; /* row to start search */ 


as —>column =1; /* column to start search */ 
return = g32_search(as,”PATTERN” ); 


/*Send a clear key to the host *? 
strepy (buffer, "CLE/0"”); 
return = g32_ send _ keys(as, buffer); 
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/* Turn notification off */ 
return = g32_notify(as,0); 


Implementation Specifics 


Files 


The g32_get_cursor function is part of the AIX 3270 Host Connection Program/6000 
(HCON). 


The g32_get_cursor function requires one of the following network communication 
adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_get_cursor function requires one of the following IBM System/370 operating 
system environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP 
TSO/E, or MVS/XA TSO/E. 


The g32_get_cursor function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/usr/include/g32const.inc Defines Pascal API constants 

/usr/include/g32hfile.inc Defines Pascal API external definitions 

/usr/include/g32types.inc Defines Pascal API data types 


Related Information 


Additional logical terminal interface functions are the g32_get_data function, 
g32_send_keys function, g32_notify function, and g32_search function. 


AIX session control functions are the g32_alloc function, g32_close function, g32_dealloc 
function, g32_open function, and g32_openx function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interface, Understanding the AIX Interface for HCON API, API error codes, Sane Flows of 
API Programs in Communications Programming Concepts. 
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g32_get_data Function 


Purpose 

Obtains current specified display data from the presentation space. 
Library 

HCON Library 

C (libg3270.a) 

Pascal (libg3270p.a) 

FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 
g32_get_data(as, buffer) 


struct g32_api *as; 
char *buffer, 


Pascal Syntax 


function g32data (var as : g32_api; 
buffer : integer) : integer; external; 


FORTRAN Syntax 


EXTERNAL G32GETDATA 
INTEGER AS(9), GZ2GETDATA 
CHARACTER *XX Buffer 


RC = G32GETDATA(AS, Buffer) 


Description 
The g32_get_data function obtains current display data from the presentation space. If the 
Starting offset in the buffer plus the transfer length is greater than the size of the presentation 
space, the transfer wraps from the last buffer position to the first and the transfer continues 
from there until the transfer length is exhausted. 


Note: The address of a packed array can be obtained by using the addr() system call: 
Buffer : = addr (<message array name> [1 (one)}) 


The g32_get_data function can only be used in API/3270 session mode. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 


C Parameters 


as Specifies a pointer to the g32_api structure containing the row (row) and 
column (column) address where the data begins, and the length (length) of 
data to return. Status information is also returned in this structure. 


_ buffer — Specifies a pointer to a buffer where the data is placed. 
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Pascal Parameters 


as 


Specifies the g32_api structure as an array of integers. 


buffer Specifies an address of a character-packed array. The array must be the 


same length or greater than the length field in the g32_api structure. 


FORTRAN Parameters 


AS Specifies the g32_api equivalent structure. 


Buffer Specifies the character array that receives the retrieved data. The array 


must be the same length or greater than the length field in the g32_api 
structure. 


Note: If the size of the buffer is smaller than AS(LENGTH), a memory fault may occur. 


Return Values 
Upon successful completion: 


e A value of 0 is returned. 


Upon unsuccessful completion: 


e An error code —1 is returned. 


e The errcode bit is set to the error code identifying the error. 


e The xerrinfo bit can be set to give more information about the error. 


Examples 
C Language | 


1. 


The following example fragment illustrates the use of the g32_get_data function in an 
api_3270 mode program: 


Note: The following example is missing the required g32_open and g32_alloc 
functions which are necessary for every HCON Workstation API program. 


#include <g32_api.h> /* API include file */ 

main() 

struct g32 api *as; /* g32 structure */ 

char *buffer; /* pointer to char string */ 

int return; /* return code */ 

char *malloc(); /* C memory allocation function */ 
return = g32_notify(as,1); /* Turn notification on */ 

buffer = malloc(10); 

return = g32_get_cursor(as); /* get location of cursor */ 


printf (” The cursor positionis row: %d col: %d/n"”; 

as —> row, as —> column); 
/* Get data from host starting at the current row and column */ 
as —> length = 10; /* length of a pattern on host */ 
return = g32_get_data(as,buffer); /* get data from host */ 
printf(“The data returned is <%s>\n",buffer); 
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/* Try to search for a particular pattern on host */ 

as —>row =1; /* row to start search */ 

as —>column =1; /* column to start search */ 
return = g32_search(as,”PATTERN”); 


/*Send a clear key to the host *? 
strepy (buffer, "CLE/0"”); 
return = g32_send_keys(as, buffer); 


/* Turn notification off */ 
return = g32_notify(as,0); 


Implementation Specifics 


Files 


The g32_get_data function is part of the AIX 3270 Host Connection Program/6000 (HCON). 
The g32_get_data function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_get_data function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The g32_get_data function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/usr/include/g32const.inc Defines Pascal API constants 

/usr/include/g32hfile.inc Defines Pascal API external definitions 

/usr/include/g32types.inc Defines Pascal API data types 


Related Information 
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Additional Logical Terminal Interface functions are the g32_get_cursor function, g32_notify 
function, g32_search function, and g32_send_keys function. 


AIX session control functions are the g32_alloc function, g32_close function, g32_dealloc 
function, g32_open function, and g32_openx function. 


The API file transfer function is the g32_fxfer function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interface, Understanding the AIX Interface for HCON API, API error codes, Sample Flows of 
API Programs in Communications Programming Concepts. 
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g32_get_status Function 


Purpose 

Returns status information of the logical path. 
Library 

HCON Library 

C (libg3270.a) 

Pascal (libg3270p.a) 

FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 


g32_get_status(as) 
struct g32_api *as; 


Pascal Syntax 
function g32stat (var as: g32_api) : integer; external; 


FORTRAN Syntax 
EXTERNAL G32GETSTATUS 
INTEGER AS(9),G32GETSTATUS 


RC = G32GETSTATUS(AS) 


Description 
The g32_get_status function obtains status information about the communication path. The 
function is called after an AIX API application determines that an error has occurred while 
reading from or writing to the communication path or after a time out. The HCON session 
profile specifies the communication path. 


Note: The g32_get_status function can only be used in API/API or API/API_T mode. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 


C Parameter 


as Specifies a pointer to a g32_api structure; status is returned in this 
structure. 


Pascal Parameter 


as Specifies the g32_api structure. 
FORTRAN Parameter 
AS Specifies a g32_api equivalent structure as an array of integers. 


Note: This function is used to determine the condition or status of the link. It should not be 
used to determine whether the previous I/O operation was successful or 
unsuccessful (the return code will provide this information). 
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Return Values 


Upon successful completion: 

e A value of 0 is returned. 

The values of errcode are as follows: 

e No error has occurred (G32_NO_ERROR, error value = 0). 


e Acommunications check has occurred (G32_COMM_CHK, error value = —1). 


e A program check has occurred within the emulator (G82_PROG_CHK, error value = —2). 


e Amachine check has occurred (G32_MACH_CHK, error value = —3). 


If errcode is anything other than G2_NO_ERROR, then xerrinfo contains an emulator 


program error code. 

Upon unsuccessful completion: 

e Anerror code of —1 is returned. 

e The errcode bit is set to the error code identifying the error. 


e The xerrinfo bit can be set to give more information about the error. 


Example 
C Language 
1. The following example fragment illustrates the use of the g32_get_status function: | 
#include <g32_api.h> /* API include file */ 
main{ ) 
{ 
struct g32 api *as; /* g32 structure */ 


int return; 


return = g32_write(as, mssg, length); 
/* see if unsucessful */ 
if (return < 0) { 
return = g32_ get_status(as); 
printf(“Return from g32_get_status = %d \n”,return); 
printf(”errcode = ¢d xerrinfor = %d \n", 
as —> errcode , as —> xerrinfo 


Implementation Specifics 
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The g32_get_status function is part of the AIX 3270 Host Connection Program/6000 
(HCON). 
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Files 


g32_get_status 


The g32_get_status function requires one of the following network communication 
adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non-—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_get_status function requires one of the following IBM System/370 operating 
system environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP 
TSO/E, or MVS/XA TSO/E. 


The g32_get_status function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/usr/include/g32const.inc Defines Pascal API constants 

/usr/include/g32hfile.inc Defines Pascal API external definitions 

/usr/include/g32types.inc Defines Pascal API data types 


Related Information 


Additional message interface functions are the g32_read function and g32_write function. 


AIX session control functions are the g32_alloc function, g32_close function, g32_dealloc 
function, g32_open function, and g32_openx function. 


The API file transfer function is the g32_fxfer function. 


Host interface functions are the G32ALLOC function, G2DLLOC function, G32READ 
function, and G32WRITE function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the AIX Interface for HCON API, API error codes, Sample Flows 
of API Programs in Communications Programming Concepts. 
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g32_notify Function 


Purpose : 
Turns data notification On or Off. 
Library 
HCON Library 
C (libg3270.a) 
Pascal (libg3270p.a) 
FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 


g32_notify(as, note) 
struct g32_api *as; 
int note; 


Pascal Syntax 


subroutine g32Note (var as : g32_api; 
note : integer) : integer; external; 


FORTRAN Syntax 
EXTERNAL G32NOTIFY 
INTEGER AS(9), Note, G32NOTIFY 


RC = G32NOTIFY(AS, Note) 


Description 
The g32_notify subroutine is used to turn notification of data arrival On and Off. The 
g32_notify subroutine may be used only by applications in API/3270 session mode. 


If an application wants to know when the emulator receives data from the host, it turns 
notification On. This causes the emulator to send a message to the application whenever it 
receives data from the host. The message is sent to the IPC message queue who's file 
pointer is stored in the eventf field of the as data structure. The application may then use 
the poll system call to wait for data from the host. Once notified the application should clear 
notification messages from the IPC queue using the msgrcv subroutine. When the 
application no longer wants to be notified, it should turn notification Off with another 
g32_notify call. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 


C Parameters 


as Specifies a pointer to the g32_api structure. Status is returned in this 
structure. 
note Specifies to turn notification Off (if the note parameter is zero) or On (if the 


note parameter is nonzero). 
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Pascal Parameters 
as Specifies a g32_api structure. 


note 


parameter is zero) or On (if the note parameter is nonzero). 


FORTRAN Parameters 


AS Specifies a g32_api equivalent structure as an array of integers. 


Note 


Return Values 
Upon successful completion: 


e Avalue of 0 is returned. 


Upon unsuccessful completion: 


Example 
C Language 
4 


An error code —1 is returned. 
The errcode bit is set to the error code identifying the error. 


The xerrinfo bit can be set to give more information about the error. 


. The following example fragment illustrates the use of the g32_notify function in an 


api_3270 mode program: 


Note: The following example is missing the required g32_open and g32_alloc 
functions which are necessary for every HCON Workstation API program. 


Specifies an integer that signals whether to turn notification Off (if the note 


Specifies to turn notification Off (if Note is zero) or On (if Note is nonzero). 


#include <g32_api.h> /* API include file 
main() 
{ 
struct g32_api *as; /* g32 structure 
char *buffer; /* pointer to char string 
int return; /* return code 
char *malloc(); /* C memory allocation function */ 
return. = g32_notify(as,1); /* Turn notification on */ 
buffer = malloc(10); 
return = g32_get_cursor(as); /* get location of cursor wf 
printf (“ The cursor positionis row: %d col: %d/n”; 
as —> row, as —> column); 

/* Get data from host starting at the current row and column * / 
as —> length = 10; /* length of a pattern on host */ 
return = g32_get_data(as,buffer);/* get data from host */ 
printf(”The data returned is <%s>\n",buffer); 
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/* Try to search for a particular pattern on host * / 
as —>row =1; /* row to start search */ 
as —>column =1; /* column to start search * / 


return = g32_search(as,”PATTERN”) ; 


strepy (buffer, "CLE/0"”); 
return = g32_ send _keys(as, buffer); /* Send clear key to host */ 


return = g32_notify(as,0); /* Turn notification off */ 


Implementation Specifics 


Files 


The g32_notify function is part of the AIX 3270 Host Connection Program/6000 (HCON). 
The g32_notify function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—-SNA distributed function terminal (nNon-—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_notify function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The g32_notify function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/usr/include/g32const.inc Defines Pascal API constants. 

/usr/include/g32hfile.inc Defines Pascal API external definitions. 

/usr/include/g32types.inc Defines Pascal API data types. 


Related Information 


Additional logical terminal interface subroutines are the g32_get_cursor subroutine, 
g32_get_data subroutine, g32_search subroutine, and g32_send_keys subroutine. 


AIX session control functions are the g32_alloc function, g32_close function, g32_dealloc 
function, g32_open function, and g32_openx function. 


The API file transfer function is the g32_fxfer function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the AIX Interface for HCON API, API error codes, Sample Flows 
of API Programs in Communications Programming Concepts. 
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g32_open Function 


Purpose | 

Attaches to a session. If the session does not exist, the session is started. 
Library 

HCON Library 

C (libg3270.a) 

Pascal (libg3270p.a) 

FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 


g32_open(as, flag, uid,pw,sessionname) 
struct g32_api *as; 

int flag; 

char * uid; 

char * pw; 

char * sessionname; 


Pascal Syntax 
function g320pen(var as : 932_api; flag : integer; 
uid : stringptr; 
pw : stringptr; 
sessionname : stringptr,) : integer; external; 


FORTRAN Syntax 


INTEGER G320PEN, RC, AS(9), FLAG 
EXTERNAL G320PEN 
CHARACTER*XX UID, PW, SESSIONNAME 


RC = G320PEN(AS, FLAG, UID, PW, SESSIONNAME) 


Description 
The g32_open function attaches to a session with the host. If the session does not exist, 
the session is started (i.e. implicit). The user is logged on to the host if request. This 
function is a subset of the capability provided by the g32_openx function. An application 
program must call the g32_open or g32_openx function before calling any other API 
function. If an API application is running implicitly an implicit logon is performed. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 


C Parameters 


as Specifies a pointer to the g32_api structure. Status is returned in this 
structure. 
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flag 


uid 


pw 


sessionname 


Pascal Parameters 
as 


flag 


Signals whether the logon procedure should be performed. Flag values 
are as follows: 


e Ifthe emulator is running and the user is logged on to the host, the 
value of the flag parameter must be 0 (zero). 


e Ifthe emulator is running, the user is not logged on to the host, and the 
API logs on to the host, the value of the flag parameter must be set to 
1 (one). 


e Ifthe emulator is not running and the API application executes an 
implicit logon/logoff procedure, the value of flag parameter is ignored. 


If the g32_open function is to log on to the host, the uid parameter 
specifies a pointer to the logon ID string. If the logon ID is a null string, 
the Logon procedure prompts the user for both the logon ID and the 
password unless the host login ID is specified in the session profile in 
which case the user is prompted only for a password. The logon IDis a 
string consisting of the host user ID and, optionally, a list of 
comma-separated AUTOLOG variables, which is passed to the implicit 
procedure. The following is a sample list of AUTOLOG variables: 


userid, node_id, trace, time=n,... 


Specifies a pointer to the password string associated with the logon ID 
string. The following usage considerations apply to the pw parameter: 


e Ifno password is to be specified, the user can specify a null string. 


e If no value is provided and the program is running implicitly, the logon 
procedure prompts the user for the password. 


e ifthe uid parameter is a null string, the ow parameter is ignored. 


Specifies a pointer to the name of a session. The session name is a 
single character in the range of a—-z. Capital letters are interpreted as 
lowercase letters. 


Specifies the g32_api structure. 


Signals whether the logon procedure should be performed. 


e If the emulator is running, the user is logged on to host, and the API 


application executes as a subshell of the emulator, the value of the flag 
parameter must be 0 (zero). 


If the emulator is running, the user is not logged on to host, and the API 
application executes as a subshell of the emulator and the application is 
to perform an implicit logon/logoff procedure, the value of the flag 
parameter must be set to 1 (one). 


If the emulator is not running and the API application executes an implicit 
logon/logoff procedure, the value of flag parameter is ignored. 
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uid Specifies a pointer to the logon ID string. If the user ID is a null string, the 
Logon procedure prompts the user for both the user ID and the password 
unless the host login ID is specified in the session profile. In the latter case, 
the user is prompted only for a password. 


pw Specifies a pointer to the password string associated with the logon ID 
string. If it points to a null string, the Logon procedure prompts the user for 
the password. This parameter is ignored if the uid parameter is a null string. 


sessionname Specifies a pointer to the name of a session, which indicates the host 
connectivity to be used by the API application. The session name is a 
single character in the range of a—z. Capital letters are interpreted as 
lowercase letters. 


FORTRAN Parameters 


When creating strings in FORTRAN that are to be passed as parameters, the strings must 
be terminated by with a null character CHAR(0). 


AS Specifies the g32_api equivalent structure as an array of integers. 
FLAG Signals whether the logon procedure should be performed. 
UID Specifies a pointer to the logon ID string. If the user ID is a null string, the 


Logon procedure prompts the user for both the user ID and the password 
unless the host login ID is specified in the session profile. In the latter case, 
the user is prompted only for a password. 


PW Specifies a pointer to the password string associated with the logon ID 
string. If the parameter specifies a null string, the Logon procedure prompts 
the user for the password. This parameter is ignored if the uid parameter is 
a null string. 


SESSIONNAME 


Specifies the name of a session, which indicates the host connectivity to be 
used by the API application. The session name is a single character in the 
range of a—z. Capital letters are interpreted as lowercase letters. 


Return Values 
Upon successful completion: 
e A value of 0 is returned 
e The Ipid bit is set to the session ID. 
Upon unsuccessful completion: 
e A value of —1 is returned. 
e The errcode bit is set to an error code identifying the error. 


e The xerrinfo bit can be set to give more information about the error. 
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Examples 


1.¢€ 

#include <g32_api.h> 

main() 

{ 
struct g32_ api *as, asx; /* asx is statically declared */ 
int flag=0; 
int ret; 
char uid[30],pw[30]; 
char *sn; 
char nm=’a’'; 
int log=0; 
as = &asx; /* as points to an allocated structure */ 
sn = &nm; 
ret=g32 open(as,log,uid,pw,sn); 

} 

2. Pascal: 

program apitest (input, output); 

const 

include /usr/include/g32const.ine 

type 


include /usr/include/g32types.inc 


var 


as : g32_ api; 

reo anteger? 

flag : integer; 

si. + istringptr> 

ret : integer; 

uid, pw : stringptr; 


S$include /usr/include/g32hfile.inc 


begin 
flag := 0; 
new(uid,20); 
uid@ := chr(0); 


end. 


new (pw,20); 

pw@ := chr(0); 

new (sn,1); 

sn@ := ‘a’; 

ret := g32open(as,flag,uid,pw,sn); 
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3. FORTRAN: 


INTEGER G320PEN 
INTEGER RC, AS(9), FLAG 
CHARACTER*20 UID 
CHARACTER*10 PW 
CHARACTER*1 SN 
EXTERNAL G320PEN 
UID = CHAR(0) 
PW = CHAR(0) 
SN = 'a’//CHAR(0) 
FLAG = 0 
RC = G320PEN(AS, FLAG, UID, PW, SN) 


Implementation Specifics 


Files 


The g32_open function is part of the AIX 3270 Host Connection Program/6000 (HCON). 
The g32_open function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_open function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The g32_open function does not feature Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/usr/include/g32const.inc Defines Pascal API constants 

/usr/include/g32hfile.inc Contains Pascal API external definitions 

/usr/include/g32types.inc Defines Pascal API data types 


‘Related Information 


Additional session control functions are the g32_alloc function, g32_close function, 
g32_dealloc function, and g32_openx function. 


Additional logical terminal interface functions are the g32_get_cursor function, | 
g32_get_data function, g32_notify function, g32_search function, and g32_send_keys 
function. 


AIX message interface functions are the g32_get_status function, g32_read function, and 
g32_write function. 


The API file transfer function is the g32_fxfer function. 
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Host interface functions are the G32ALLOC function, GZ2DLLOC function, GZ2READ 
function, and G32WRITE function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the AIX Interface for HCON API, API error codes, Sample Flows 
of API Programs in Communications Programming Concepts. 
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g32_openx Function 


Purpose | 
Attaches to a session and provides extended open capabilities. If the session does not 
exist, the session is started. 
Library 
HCON Library 
C (libg3270.a) 
Pascal (libg3270p.a) 
FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 

g32_openx(as, flag, uid, pw, sessionname, timeout) 
struct g32_api *as; 

int flag; 

char * uid; 

char * pw; 

char * sessionname; 

char * timeout; 


Pascal Syntax 
function g32openx(var as : g32_api; flag: integer; 
uid : stringptr; 
pw: stringptr; 
sessionname : stringptr; 
timeout : stringptr) : integer; external; 


FORTRAN Syntax 
INTEGER G320PENX,RC,AS(9),FLAG 
EXTERNAL G320PEN 
CHARACTER* XX UID, PW, SESSIONNAME 
RC = G320PEN (AS, FLAG, UID, PW, SESSIONNAME, TIMEOUT) 


Description 
The g32_openx function attaches to a session. If the session does not exist, the session is 
started. This is an implicit logon. The user is logged on to the host if requested. The 
g32_openx function provides additional capability beyond that of the g32_open function. 
An application program must call g32_openx or g32_open before any other API function. 


If an API application is run implicitly, the function performs an implicit logon is performed. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 
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C Parameters 
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The g32_openx function allows for a varying number of parameters after the ‘flag 
parameter. This function uses two required parameters: as and flag plus the optional 
parameters: uid, pw, session, and timeout. 


With the g32_open function, the timeout parameter does not exist and the parameters for 
uid, pw, and session are not optional. The reason for making the last four parameters 
optional is that the system either prompts for the needed information (uid and pw) or defaults 
with valid information (session or timeout). 


Unless all of the parameters are defined for this function, the parameter list in the calling 
statement must be terminated with the integer 0 (zero) (like the exec function). Providing an 
integer of 1 forces a default on an parameter. Use the default to provide a placeholder for 
optional parameters that you do not need to supply. 


as Specifies a pointer to the g32_api structure. 
flag Requires one of the following: 


e Set the flag parameter to 0 (zero), if the emulator is running and the user 
is logged on to host. 


e Set the flag parameter to 1 (one) if the emulator is running, the user is not 
logged on to host, and the API application is to perform the logon/logoff 
procedure. 


The g32_open function ignores the flag parameter, if the emulator is not 
running and the API application executes an implicit logon/logoff procedure. 


uid Specifies a pointer to the logon ID string. If the logon ID is a null string, the 
Logon procedure prompts the user for both the logon ID and the password, 
unless the host login ID is specified in the session profile. In the latter case 
the user is prompted only for a password. The logon ID is a string consisting 
of the host user ID and, optionally, a list of additional variables separated by 
session, as shown in the example: 


userid,varl,var2,... 


In this example, var? is the logon script name (when using AUTOLOG) and 
var2 is the optional trace and time values. The list is passed to the implicit 
procedure. 


pw Specifies a pointer to the password string associated with the logon ID 
string. The following usage considerations apply to the pw parameter: 


e If no password is to be specified, the user can specify a null string. 


e If no value is provided and the program is running implicitly, the logon 
procedure prompts the user for the password. 


e Ifthe u/d parameter is a null string, the pw parameter is ignored. 


sessionname Points to the name of a session. The session name is a single character in 


the range of a—z. Capital letters are interpreted as lowercase letters. 
Parameters for each session are specified in a per—session profile. 
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timeout 


Pascal Parameters 


g32_openx 


Specifies a pointer to a numerical string (such as 30 or 60) that specifies the 
amount of nonactive time (in seconds) allowed to occur between the 
workstation and the host operations (that is, g32_read/G32WRITE). This 
parameter is optional. If no value is provided in the calling statement, the 
default value is 15 seconds. The minimum value allowed is 1. There is no 
maximum value limitation. 


When using C as a programming language, you can make use of the feature of variable 
numbered parameters. In Pascal, however, this feature is not allowed. Therefore, calls to the 
g32_openx function must contain all six parameters. 


To use defaults for the four optional parameters of C, provide a variable whose value is a 


null string. 


Note: The use of the integer one (1) is not allowed in the Pascal version of the g32_openx 
function. Space must be allocated for any string pointers prior to calling the 
g32_openx function. 


as 


flag 


uid 


pw 


sessionname 


timeout 


Specifies the g32_api structure. 
Signals whether the logon procedure should be performed. 


e Set the flag parameter to 0 (zero), if the emulator is running, the user is 
logged on to host. 


e Set the flag parameter to 1 (one), if the emulator is running, the user is 
not logged on to host, and the API application performs the logon/logoff 
procedure. 


e \f the emulator is not running and the API application executes an implicit 
logon/logoff procedure, the value of flag is ignored. 


Specifies a pointer to the logon ID string. If the logon ID is a null string, the 
logon procedure prompts the user for both the logon ID and the password, 
unless the host login ID is specified in the session profile. In the latter case 
the user is prompted only for a password. 


Specifies a pointer to the password string associated with the logon ID 
string. The following usage considerations apply to the pw parameter: 


e Ifno password is to be specified, the user can specify a null string. 


e lf no value is provided and the program is running implicitly, the logon 
procedure prompts the user for the password. 


e Ifthe uid parameter is a null string, the pw parameter is ignored. 


Points to the name of a session. The session name is a single character in 
the range of a—z. Capital letters are interpreted as lowercase letters. 
Parameters for each session are specified in a per session profile. 


Specifies a pointer to a numerical string (such as 30 or 60) that specifies the 
amount of nonactive time (in seconds) allowed to occur between the 
workstation and the host operations (that is, g32_read/g32WRITE). This 
parameter is optional. !f no value is provided in the calling statement, the 
default value is 15 seconds. The minimum value allowed is one. There is 
no maximum value limitation. 
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FORTRAN Parameters 
FORTRAN calls to G32_OPENX must contain all six parameters. To use defaults for the 
four optional parameters of C language, provide a variable whose value is a null string. 
Note that the use of the integer 1 (one) is not allowed in the FORTRAN version of this 
function. When creating strings in FORTRAN that are to pass as parameters, the strings 
must be linked with a null character, CHAR (0). 


AS 
FLAG 


UID 


PW 


SESSIONNAME 


TIMEOUT 


Return Values 


Specifies the g32_api equivalent structure as an array of integers. 


Signals that the logon procedure should be performed. 


e Set the Flag parameter to 0 (zero), if the emulator is running, the user is 
logged on to host. 


e Set the Flag parameter to 1 (one), if the emulator is running, the user is 
not logged on to host. 


e |f the emulator is not running and the API application executes an implicit 
logon/logoff procedure, the value of Flag is ignored. 


Specifies a pointer to the logon ID string. If the logon ID is a null string, the 

logon procedure prompts the user for both the logon ID and the password, 

unless the host login ID is specified in the session profile. In the latter case 
the user is prompted only for a password. 


Specifies a pointer to the password string associated with the logon ID 
string. The following usage considerations apply to the pw parameter: 


e If no password is to be specified, the user can specify a null string. 


e If no value is provided and the program is running implicitly, the logon 
procedure prompts the user for the password. 


e Ifthe uid parameter is a null string, the pw parameter is ignored. 


Specifies the name of a session. The session name is a single character in 
the range of a—z. Capital letters are interpreted as lowercase letters. 
Parameters for each session are specified in a per session profile. 


Specifies a numerical string (such as 30 or 60) that specifies the amount of 
nonactive time (in seconds) allowed to occur between the workstation and 
the host operations (that is, g32_read/g32WRITE). There is no maximum 
to this, but the minimum is 1 (one). 


Upon successful completion: 


e A value of 0 is returned. 


e The Ipid bit is set to the session ID. 


Upon unsuccessful completion: 


e Avalue of —1 is returned. 


e The errcode bit is set to an error code identifying the error. 


e The xerrinfo bit can be set to give more information about the error. 
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Examples of ways to use the g32_openx function are as follows: 


A 


With fewer than four optional string constant parameters specified and used with 


AUTOLOG: 


g32_openx (AS, 0, “john, tso, trace”, "j12hn”); 


With fewer than four optional string constant parameters specified and used with LAF: 


g32 openx (AS, 1, “john”, “jl2hn", "2", 


. With all optional parameters not specified: 


g32_openx (AS, 1, 0); 
or 
g32_openx (AS, 0, 0); 


. With four variable optional parameters: 


g32_openx (AS, 0, UID, Pw, Sessionname, 


. With fewer than four variable optional parameters: 


g32 openx (AS, 1, UID, Pw, 0); 


. With two default optional parameters: 


g32.openx (AS; 0-1, Ly. 1, %60")4 


. With a mixture: 


g32_openx (AS, 0, 1, 1, Session, 0); 


0); 


TimeOut ); 


The following examples illustrate the use of the g32_openx function within a program 
segment in the C, Pascal, and FORTRAN languages: 


1 


C: 


#include <g32_api.h> 
main({ ) 


{ 


struct g32_api *as, asx; /* asx is a temporary struct */ 
/* g32.api so that storage */ 
/* is allocated */ 


int flag=0; 

int ret; 

char uid[30],pw[30]; 
char *sn; 

char nm='a’; 

char timeout="60"; 
int log=0; 


sn 
as 


&nm; 


&aSX; /* as points to an allocated structure */ 


ret=g32_ openx(as,flag,uid,pw,sn,timeout) ; 
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2. Pascal: 

program apitest (input, output); 
const 
include /usr/include/g32const.inc 
type 
include /usr/include/g32types.inc 
var 

as : g32_api; 

re : integer; 

flag : integer; 

sn : stringptr; 

timeout : stringptr; 

ret : integer; 

uid, pw : stringptr; 
include /usr/include/g32hfile.inc 
begin 

flag <= 0; 

new(uid,20); 

uid@ := chr(0); 

new (pw,20); 

pw@ := chr(0); 

new (sn,1); 

sn@ := ‘a’; 

new (timeout, 32); 

timeout@ := ‘60’; 

ret := g32o0penx(as,flag,uid,pw,sn,timeout); 
end. 

_ 3. FORTRAN: 


INTEGER G320PENX 


INTEGER RC, AS(9), 


FLAG 


CHARACTER*20 UID 
CHARACTER*10 PW 
CHARACTER*10 TIMEOUT 
CHARACTER*1 SN 
EXTERNAL G320PENX 


UID 
TIMEOUT 
MODEL 
PW 
SN ‘a’ 
TIMEOUT 
FLAG 
RC 
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_ 


0 
G320PENX(AS, 


CHAR(0) 


CHAR (0) 


CHAR (0) 
CHAR(0) 


//CHAR(0) 
'60’//CHAR(0) 


FLAG, UID, PW, SN, TIMEOUT) 
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Implementation Specifics 


Files 


The g32_openx function is part of the AIX 3270 Host Connection Program/6000 (HCON). 
The g32_openx function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non-—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_openx function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The g32_openx function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/ust/include/g32const.inc Defines Pascal API constants 

/usr/include/g32hfile.inc Defines Pascal API external definitions 

/usr/include/g32types.inc Defines Pascal API data types 


Related Information 


Additional session control functions are the g32_alloc function, g32_close function, 
g32_dealloc function, and g32_open function. 


Additional logical terminal interface functions are the g32_get_cursor function, 
g32_get_data function, g32_search function, g32_notify function, and g32_send_keys 
function. 


AIX message interface functions are the g32_get_status function, g32_read function, and 
g32_write function. 


The API file transfer functions is the g32_fxfer function. 


Host interface functions are the G32ALLOC function, G32DLLOC function, GZ2READ 
function, and G32WRITE function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the AIX Interface for HCON API, API error codes, Sample Flows 
of API Programs in Communications Programming Concepts. 
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G32READ Function 


Purpose 
Receives a message from the AIX API application running simultaneously on the RISC 
System/6000. 

Syntax 
G32READ 

Description 


The G32READ function receives a message from an AIX API application. The G32READ 


function returns when a message is received. The status of the transmission is returned in 
register zero (RO). 


The G32READ function returns the following values: 
RO Is the number of bytes read. 


R1 Is the address of the message buffer. 


Return Values 
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The G32READ function sets register zero (RO) to the following values: 


>= 0 Normal return. This is the length of the message (the number of bytes 
read). 
<0 Less than zero. Host API error condition. 


In VM/CMS, storage for the read command is obtained using the DMSFREE macro. RO 
contains the number of bytes read. R1 contains the address of the buffer. It is the 
responsibility of the host application to release the buffer with a DMSFRET call. Assuming 
the byte count and address are in RO and R1, respectively, the following code fragment 
should be used to free the buffer: 


SRL R0,3 
A RO,=F’'1! 
DMSFRET DWORDS=(0),LOC=(1) 


In MVS/TSO, storage for the READ command is obtained using the GETMAIN macro. RO 
contains the number of bytes read. R1 contains the address of the buffer. The host 
application must release the buffer with a FREEMAIN call. 


In MVS/TSO, when programming an API assembly language application, you must be 
careful with the TPUT macro. If it is used in a sequence of GG2READ and G32WRITE 
subroutines, it will interrupt the API/API mode and switch the host to API/3270 mode to exist. 
You will not be able to get the AP!/API mode back until you send the Enter key. 
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Example 
The following 370 Assembler code example illustrates the use of the host GZ2READ 
function: 
MEMORY L_ 12,=v(G32DATA) /* SET POINTER TO API DATA AREA */ 


L 2,=F‘2' 


G32READ /* RECEIVE MESSAGE FROM AIX */ 
ST 1,ADDR /* STORE ADDRESS OF MESSAGE */ 
ST 0,LEN /* STORE LENGTH OF MESSAGE */ 


BAL 14,CHECK 


Implementation Specifics : 
The G32READ function is part of the AIX 3270 Host Connection Program/6000 (HCON). 


The G32READ function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The G32READ function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The G32READ function is not available for Jaoanese Language Support. 


Related Information 
Additional host interface functions are the GZ2ALLOC function, G32DLLOC function, and 
G32WRITE function. 


AIX session control subroutines are the g32_alloc subroutine, g32_close subroutine, 
g32_dealloc subroutine, g32_open subroutine, and g32_openx subroutine. 


AIX message interface subroutines are the g32_get_status subroutine, g32_read 
subroutine, and g32_write subroutine. 


For documentation on the DMSFREE and DMSFRET macros, consult the VM/SP System 
Programmer's Guide. 


For documentation on the GETMAIN and FREEMAIN macros, consult the MVS/XA System 
Macros and Facilities, Volume 2 or MVS/XA Supervisor Services and Macro Instructions. 
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HCON Overview for Programming, Understanding the HCON Application Programming 


Interfaces, Understanding the HCON Host Interface in Communications Programming 
Concepts. 


How to Compile a Host HCON API Program, Host API Errors, Sample Flows of API 
Programs in Communications Programming Concepts. 
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g32_read Function 


Purpose 

Receives a message from a host application. 
Library 

HCON Library 

C (libg3270.a) 

Pascal (libg3270p.a) 

FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 


g32_read (as, msgbuf, msglen) 
struct g32_api *as; 

char **msgbuf; 

int *msgien, 


Pascal Syntax 
function g32read (var as : g32_api; 


var Buffer : stringptr; 
var msglen : integer : integer; external; 


FORTRAN Syntax 
EXTERNAL G32READ 
INTEGER AS(9), BUFLEN, G32READ 
INTEGER AS(9), BUFLEN, G32READ 
CHARACTER *XX MSGBUF 


RC= G32READ (AS, MSGBUF, BUFLEN) 


Description 
The g32_read function receives a message from a host application. The g32_read function 
may only be used by those applications having API/API or API/API_T mode specified with 
the g32_alloc function. 


e In Cor Pascal, a buffer is obtained, a pointer to the buffer is saved, and the message 
from the host is read into the buffer. The length of the message and the address of the 
buffer are returned to the user application. 


e In FORTRAN, the calling procedure must pass a buffer large enough for the incoming 
message. The BUFLEN parameter must be the actual size of the buffer. The GB2READ 
function uses the BUFLEN parameter as the upper array bound. Therefore, any 
messages larger than BUFLEN are truncated to fit the buffer. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 
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C Parameters 
as Specifies a pointer to a g32_api structure. 


msgbuf Specifies a pointer to a pointer to a buffer where a message from the host is 
placed. The API obtains space for this buffer by using the AIX malloc library 
subroutine, and the user is responsible for releasing it by issuing a free call 
after the g32_read function. 


msglen Specifies a pointer to an integer where the length, in bytes, of the msgbuf 
parameter is placed. The message length must be greater than 0 (zero) but 
less than or equal to the maximum I/O buffer size parameter specified in the 
HCON session profile. 


Pascal Parameters 
as Specifies the g32_api structure. 


Buffer Specifies a stringptr. The API obtains space for this buffer by using the AIX 
malloc C library subroutine, and the user is responsible for releasing it by 
issuing a dispose subroutine after the g32_read function. 


msglen Specifies an integer where the number of bytes read is placed. The 
message length must be greater than 0 (zero) but less than or equal to the 
maximum I/O buffer size parameter specified in the HCON session profile. 


FORTRAN Parameters 


AS Specifies the g32_api equivalent structure. 
MSGBUF Specifies the storage area for the character data read from the host. 
BUFLEN Specifies the size, in bytes, of the value contained in the MSGBUF 


parameter. The message length must be greater than 0 (zero) and less 
than the maximum I/O buffer size parameter specified in the HCON 
session profile. 


Return Values 
Upon successful completion: 
e The number of bytes read is returned (= 0 ). 
Upon unsuccessful completion: 
e An error code —1 is returned. 
e The errcode bit is set to the error code identifying the error. 


e The xerrinfo bit can be set to give more information about the error. 


Example 
C Language 
1. The following example illustrates the use of the g32read function: 
#include <g32_api> /* API include file */ 
main() 
{ 
struct g32_api *as; /* g32_api structure */ 
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char **msg_buf; /* pointer to host msg buffer */ 

char *messg; /* pointer to character string */ 

int *msg_len; /* pointer to host msg length */ 

char * malloc(); /* C memory allocation function */ 

int return; /* return code is no. of bytes read */ 
messg = malloc(30); /* allocate 30 bytes */ 

msg_buff = &messg; /* point to a string */ 

msg_len = malloc(sizeof(int)); /* allocate storage */ 


return = g32_read(as, msg_buff, msg_len); 


Implementation Specifics 


Files 


The g32_read function is part of the AIX 3270 Host Connection Program/6000 (HCON). 
The g32_read function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_read function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The g32_read function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/ust/include/g32const.inc Defines Pascal API constants 

/usr/include/g32hfile.inc Defines Pascal API external definitions 

/usr/include/g32types.inc Defines Pascal API data types 


Related Information 


Additional message interface functions are the g32_get_status function and g32_write 
function. 


AIX session control functions are the g32_alloc function, g32_close function, g32_dealloc 
function, g32_open function, and g32_openx function. 


The API file transfer function is the g32_fxfer function. 


Host interface functions are the G32ALLOC function, G32DLLOC function, GZ2READ 
function, and G32WRITE function. 
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The malloc subroutine and free subroutine. 
HCON Overview for Programming, Understanding the HCON Application Programming 


Interface, Understanding the AIX Interface for HCON API, API error codes, Sample Flows of 
API Programs in Communications Programming Concepts. 
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g32_search Function 


Purpose 


Library 


C Syntax 


Searches for a character pattern in a presentation space. 


HCON Library 

C (libg3270.a) 

Pascal (libg3270p.a) 
FORTRAN (libg3270f.a) 


#include <g32_api.h> 


g32_search(as, pattern) 
struct g32_api *as; 
char *pattern; 


Pascal Syntax 


function g32srch(var as : g32_api; 
pattern : stringptr) : integer; external; 


FORTRAN Syntax 


EXTERNAL G32SEARCH 
INTEGER AS(9), G32SEARCH 
CHARACTER *XX PATTERN 


RC = G32SEARCH(AS, PATTERN) 


Description 
The g32_search function searches for the specified byte pattern in the presentation space 


associated with the application. 


Note: The g32_search function can only be used in API/3270 mode. 


g32_search 


The search is performed from the row and column given in the g32_api structure to the end 
of the presentation space. Note that the row and column positions start at 1 (one) and not 0 


(zero). lf you start at 0 for row and column, you get invalid position errors. 


In any given search pattern, the following characters have special meaning: 


? The Question mark is the arbitrary character, matching any one character. 


® 


more characters. 


The Asterisk is the wildcard character, matching any sequence of zero or 


\ The Backslash is the escape character meaning the next character is to be 


interpreted literally. 
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The following rules apply to the use of wildcard characters: 
° The pattern can not begin with the wildcard character. 
e The pattern can not end with the wildcard character. 


e The pattern can not contain two consecutive wildcard characters. 


Pattern Matching Example 


The string AB?7DE matches any of ABCDE, AB9DE, ABxDE, but does not match ABCD, 
ABCCDE, or ABDE. : 


The string AB*DE matches any of ABCDE, AB9DE, ABCCDE, ABDE, but does not match 
ABCD, ABCDF, or ABC. 


Pattern Matching in C and Pascal: 


If the pattern needs to contain either a question mark or an asterisk as a literal character, 
these symbols must be preceded by two escape characters (\\? or \\*). For example, to 
search for the string, How are you today?, the pattern might be: 


How are you today \\? 


The backslash can be used as a literal character by specifying four backslash characters 
(\\\\) in the pattern. For example, to search for the string, We found the \., the pattern might 
be: 


We found the \\\\. 


Pattern Matching in FORTRAN: 


If the pattern needs to contain either a question mark or an asterisk as a literal character, 
these symbols must be preceded by one escape character (\? or \*). For example, to search 
for the string, How are you today?, the pattern might be: 


How are you today\? 


The backslash can be used as a literal character by specifying two backslash characters (\\) 
in the pattern. For example, to search for the string, We found the \., the pattern might be: 


We found the \\. 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 


C Parameters 


as Specifies a pointer to a g32_api structure. It also contains the row and 
column where the search should begin. Status information is returned in this 
structure. 

pattern Specifies a pointer to a byte pattern, which is searched for in the 


presentation space. 


Pascal Parameters 
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as Specifies the g32_api structure. 


Base Operating System Reference 


g32_search 


pattern Specifies pointer to a string containing the pattern to search for in the 


presentation space. The string must be at least as long as the length 
indicated in the g32_api structure. 


FORTRAN Parameters 


AS Specifies a g32_api equivalent structure as an array of integers. 

Pattern Specifies string that is searched for in the presentation space. 
Return Values 

Upon successful! completion: 

e A value of 0 is returned 


e The corresponding row element of the as structure is the row position of the beginning of 
the matched string. 


e The corresponding column element of the as structure is the column position of the 
beginning of the matched string. 


e The corresponding length element of the as structure is the length of the matched string. 
Upon unsuccessful completion: 

e An error code -1 is returned. 

e The errcode bit is set to the error code identifying the error. 


e The xerrinfo bit can be set to give more information about the error. 


Example 


C Language 
1. The following example fragment illustrates the use of the g32_search function in an 
api_3270 mode program: 


Note: The following example is missing the required g32_open and g32_alloc 
functions which are necessary for every HCON Workstation API program. 


#include <g32_api.h> /* API include file */ 
main() 
struct g32 api *as; /* g32 structure */ 
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char *buffer; | /* pointer to char string */. 

int return; /* return code */ — 

char *malloc(); /* C memory allocation function */ 
return g32_ notify(as,1); /* Turn notification on */ 

buffer malloc(10); 


return = g32_get_cursor(as); /* get location of cursor */ 
printf (”“ The cursor positionis row: %d col: %d/n”; 

as —> row, as —> column); 
/* Get data from host starting at the current row and column */ 
as —> length = 10; /* length of a pattern on host */ 
return = g32_get_data(as,buffer); /* get data from host */ 
printf(“The data returned is <%s>\n"”,buffer); 


/* Try to search for a particular pattern on host */ 

as —>row =1; /* row to start search */ 

as —>column =1; /* column to start search */ 
return = g32_search(as,”PATTERN” ); 


/*Send a clear key to the host *? 
strepy (buffer, "CLE/0"”); 
return = g32_send_keys(as, buffer); 


/* Turn notification off */ 
return = g32_notify(as,0); 


Implementation Specifics 
The g32_search function is part of the AIX 3270 Host Connection Program/6000 (HCON). 


Files 
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The g32_search function requires one of the following network communication adapters: 


IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—-SNA distributed function terminal (non—SNA 
DFT) mode. 


IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_search function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The g32_search function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/usr/include/g32const.inc Defines Pascal API constants 

/usr/include/g32hfile.inc Defines Pascal API external definitions 

/usr/include/g32types.inc Defines Pascal API data types 


Base Operating System Reference 


g32_search 


Related Information 
Additional Logical Terminal Interface functions are the g32_get_cursor function, 
g32_get_data function, g32_notify function, and g32_send_keys function. 


A!X session control functions are the g32_alloc function, g32_close function, g32_dealloc 
function, g32_open function, and g32_openx function. 


The API file transfer function is the g32_fxfer function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the AIX Interface for HCON API, API error codes, Sample Flows 
of API Programs in Communications Programming Concepts. 
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g32_send_keys Function 


Purpose 

Sends key strokes to the terminal emulator. 
Library 

HCON Library 

C (libg3270.a) 

Pascal (libg3270p.a) 

FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 
#include <g32_keys.h> 
g32_send_keys(as, buffer) 
struct g32_api *as; 

char *buffer, 


Pascal Syntax 
const 
%include /usr/include/g32keys.inc 
function g32sdky (var as : g32_api; 
buffer : stringptr) : integer; external; 


FORTRAN Syntax 


EXTERNAL G32SENDKEYS 
INTEGER AS(9), GZ2SENDKEYS 
CHARACTER *XX BUFFER 


RC = G32SENDKEYS(AS, BUFFER) 


Description 
The g32_send_keys function sends one or more key strokes to a terminal emulator as 
though they came from the keyboard. ASCII characters are sent by coding their ASCil 
value. Other keys (such as Enter and the cursor—-movement keys) are sent by coding their 


values from the g32_keys.h file (for C programs) or g32keys.inc file (for Pascal programs). 


FORTRAN users send other keys by passing the name of the key through the 
G32SENDKEYS buffer. 


The g32_send_keys function can only be used in API/3270 mode. 


C Parameters 


as Specifies a pointer to the g32_api structure. Status is returned in this 
structure. 
buffer Specifies a pointer to a buffer of key stroke data. 
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Pascal Parameters 
as Specifies the g32_api structure. Status is returned in this structure. 


buffer Specifies a pointer to a string containing the keys to be sent to the host. The 
string must be at least as long as indicated in the g32_api structure. 


FORTRAN Parameters 


AS Specifies the g32_api equivalent structure as an array of integers. 


BUFFER The character array containing the key sequence to send to the host. A 
special emulator key can be sent by the g32_send_keys function as 


follows: 


BUFFER = 'ENTER’//CHAR(0) 
RC = G32SENDKEYS (AS,BUFFER) 


The special emulator strings recognized by the g32_send_keys function 
are as follows: 


CLEAR DELETE DUP ENTER 
EOF ERASE FMARK HOME 
INSERT NEWLINE RESET SYSREQ 
LEFT RIGHT UP DOWN 
LLEFT RRIGHT UUP DDOWN 
TAB BTAB 

PAI PA2 PA3 

PF1 PF2 PF3 PF4 
PES PF6 PE] PF8 
PF9 PF10 PF 11 PF12 
PF13 PF14 PF15 PF16 
PF17 PF18 PF19  PF20 
PF21 PF22 PF23 PF24 


Return Values 
Upon successful completion: 


e A value of 0 is returned. 

Upon unsuccessful completion: 

e An error code —1 is returned. 

e The errcode bit is set to the error code identifying the error. 


e The xerrinfo bit can be set to give more information about the error. 


Examples 
C Language 
, 


. The following example fragment illustrates the use of the g32_send_keys function in an 
api_3270 mode program: 


Note: The following example is missing the required g32_open and g32_alloc 
functions which are necessary for every HCON Workstation API program. 
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#include <g32_api.h> /* API include file */ 

main( ) 

{ 

struct g32 api *as; : /* g32 structure */ 

char *buffer; /* pointer to char string */ 
int return; /* return code */ 

char *malloc(); /* C memory allocation function */ 
return = g32_notify(as,1); /* Turn notification on */ 
buffer = malloc(10); 

return = g32_get_cursor(as); /* get location of cursor */ 
printf (” The cursor positionis row: %d col: %d/n”; 


as —> row, as —> column); 
/* Get data from host starting at the current row and column */ 
as —> length = 10; /* length of a pattern on host */ 
return = g32_ get _data(as,buffer); /* get data from host */ 
printf(”The data returned is <%s>\n"”,buffer); 


/* Try to search for a particular pattern on host */ 

as —>row =1; /* row to start search */ 

as —>column =1; /* column to start search */ 
return = g32_search(as,”PATTERN” ); 


/*Send a clear key to the host *? 
strepy (buffer, "CLE/0”); 
return = g32_send_keys(as, buffer); 


/* Turn notification off */ 
return = g32_notify(as,0); 


Implementation Specifics 
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The g32_send_keys function is part of the AIX 3270 Host Connection Program/6000 
(HCON). 


The g32_send_keys function requires one of the following network communication 
adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_send_keys function requires one of the following IBM System/370 operating 
system environments be installed on the nee VM/SP CMS, VM/XA CMS, MVS/SP 
TSO/E, or MVS/XA TSO/E. 


The g32_send_keys function is not available for Japanese Language Support. 
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Files 

/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/usr/include/g32_keys.h Defines key values for C language use. 
/usr/include/g32keys.inc Defines key values for Pascal language use. 
/usr/include/g32const.inc Defines Pascal API constants. 
/usr/include/g32hfile.inc Defines Pascal API external definitions. 
/usr/include/g32types.inc Defines Pascal API] data types. 


Related Information 
Additional Logical Terminal Interface functions are the g32_get_cursor function, 
g32_get_data function, g32_notify function, and g32_search function. 


AIX session control functions are the g32_alloc function, g32_close function, g32_dealloc 
function, g32_open function, and g32_openx function. 


The API file transfer function is the g32_fxfer function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the AIX Interface for HCON API, API error codes, Sample Flows 
of API Programs in Communications Programming Concepts. 
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G32WRITE Function 


Purpose 
Sends a message to an AIX API application running simultaneously on the RISC 
System/6000. 


Syntax 
G32WRITE MSG,LEN 


Description 
The G32WRITE function sends a message to an AIX API application. The maximum number 
of bytes that may be transferred is specified by the value returned in RO after a successful 
completion of the G32ALLOC function. 


The G32 WRITE function is a HCON API function that can be called by a 370 Assembler 
applications program. 


Parameters 
MSG The address of the message to be sent. It may be: 


Label A label on a DC or DS statement declaring the message. 
O(reg) | A register containing the address of the message. 


LEN | The length, specified in bytes, of the message. It is a full word, whose contents 
cannot exceed the value returned by the G32ALLOC function in RO. It must be: 


Label The address of a full word containing the length of the message. 
Return Values 
The G32WRITE function sets register 0 (zero) to the following values: 
0 Zero. A normal return; call successful. 
<0 Less than zero. Host API error condition. 
Examples 


The following 370 Assembler code example illustrates the use of the host GZ2WRITE 
function: 


L R11,=v(G32DATA) 
USING G32DATAD,R11 


G32WRITE MSG1, LEN1 /* write “Hello” to AIX */ 
LTR RO,RO /* check return code * / 
BE WRITEOK /* if good, go to write */ 


( error code ) 


MSG1 DC C ‘HELLO’ 
LEN1 DC AL4(*—MSG1) 


2-78 Base Operating System Reference 


G32WRITE 


Implementation Specifics 
The G32WRITE function is part of the AIX 3270 Host Connection Program/6000 (HCON). 


The G32WRITE function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—-SNA distributed function terminal (non-SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The G32WRITE function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The G32WRITE function is not available for Japanese Language Support. 
Related Information 


Additional host interface functions are the G32ALLOC function, G32DLLOC function, and 
G32WRITE function. 


AIX session contro! subroutines are the g32_alloc subroutine, g32_close subroutine, 
g32_dealloc subroutine, g32_open subroutine, and g32_openx subroutine. 


AIX message interface subroutines are the g32_get_status subroutine, g32_read 
subroutine, and g32_write subroutine. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the HCON Host Interface in Communications Programming 
Concepts. 


How to Compile a Host HCON API Program, Host API Errors, Sample Flows of API 
Programs in Communications Programming Concepts. 
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g32_write Function 


Purpose 

Sends a message to a host application. 
Library 

HCON Library 

C (libg3270.a) 

Pascal (libg3270p.a) 

FORTRAN (libg3270f.a) 
C Syntax 


#include <g32_api.h> 


g32_write(as, msgbuf, msglen) 
struct g32_api *as; 

char *msgbuf, 

int msglen; 


Pascal Syntax 


function g32wrte (var as : g32_api; 
Buffer : integer; 
msglen : integer : integer; external; 


FORTRAN Syntax 


EXTERNAL G32WRITE 
INTEGER AS(9), MSGLEN, G32WRITE 
CHARACTER* XX MSGBUF 


RC = G32WRITE(AS, MSGBUF, MSGLEN) 


Description 
The g32_write function sends the message pointed to by the msgbuf parameter to the host. 
This function may only be used by those applications having API/API or API/API_T mode 
specified by the g32_alloc command. | 


HCON application programs using the Pascal language interface must include and link both 
the C and Pascal libraries. Applications programs using the FORTRAN language for the 
HCON API must include and link both the C and FORTRAN libraries. 


C Parameters 


as Specifies the pointer to a g32_api structure. 
msgbuf Specifies a pointer to a message, which is a byte string. 
msglen Specifies the length, in bytes, of the message pointed to by the msgbuf 


parameter. The value of the msg/en parameter must be greater than 0 and 
and less than or equal to the maximum I/O buffer size specified in the 
HCON session profile. 
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Pascal Parameters 


FORTRAN 


as Specifies the g32_api structure. 


g32_write 


Buffer Specifies an address of a character—packed array. 


Note: The address of a packed array can be obtained by the addr() 
function call: buffer := addr («msg array name> [1 (one)]) 


msglen Specifies an integer indicating the length of the message to send to the 
host. The msg/en parameter must be greater than 0 and less than or equal 
to the maximum I/O buffer size specified in the HCON session profile. 


Parameters 

AS Specifies the g32_api equivalent structure as an array of integers. 
MSGBUF Specifies a character array containing the data to be sent to the host. 
MSGLEN Specifies the number of bytes to be sent to the host. The MSGLEN 


parameter must be greater than 0 and less than or equal to the maximum 
\/O buffer size specified in the HCON session profile. 


Return Values 


Example 
C Language 


Upon successful completion: 


e The number of bytes written is returned (>= 0). 


Upon unsuccessful completion: 


e Anerror code —1 is.returned. 


e The errcode bit is set to the error code identifying the error. 


e The xerrinfo bit can be set to give more information about the error. 


1. The following example illustrates the use of the g32_write function: 
#include <g32_api> /* API include */ 
main() 
{ 
struct g32 api *as; /* the g32 structure */ 


char *messg; /* 


int length; /* 
char *malloc(); /* 
* / 


int return; /* 


pointer to a character string 
to send to the host */ 
Number of bytes sent */ 


C memory allocation function 


return code is no. of bytes 
sent */ 
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messg = malloc(30); /* allocate 30 bytes for the string */ 
/* initialize message string with information */ 

strcpy(messg,”“string to be sent to host/0” 

length = strlen(messg); /* length of the message */ 

return = g32_write(as,messg,length); 


Implementation Specifics 


Files 


The g32_write function is part of the AIX 3270 Host Connection Program/6000 (HCON). 
The g32_write function requires one of the following network communication adapters: 


e IBM 3270 Connection Adapter and attachment cables for connection to an IBM 
3174/3274 Control Unit, IBM 4361 Work Station Adapter, or an IBM 9370 Work Station 
Subsystem Controller configured for non—SNA distributed function terminal (non—SNA 
DFT) mode. 


e IBM System/370 Host Interface Adapter and attachment cables for connection to an IBM 
5088 Graphics Control Unit. 


The g32_write function requires one of the following IBM System/370 operating system 
environments be installed on the System/370: VM/SP CMS, VM/XA CMS, MVS/SP TSO/E, 
or MVS/XA TSO/E. 


The g32_write function is not available for Japanese Language Support. 


/usr/include/g32_api.h Contains data structures and associated symbol 
definitions. 

/usr/include/g32const.inc Defines Pascal API constants 

/usr/include/g32hfile.inc Defines Pascal API external definitions 

/usr/include/g32types.inc Defines Pascal API data types 


Related Information 


Additional message interface functions are the g32_get_status function and g32_read 
function. 


AIX session control functions are the g32_alloc function, g32_close function, g32_dealloc 
function, g32_open function, and g32_openx function. 


The API file transfer functions is the g32_fxfer function. 


Host interface functions are the G32ALLOC function, GZ2DLLOC function, GZ2READ 
function, and G32WRITE function. 


HCON Overview for Programming, Understanding the HCON Application Programming 
Interfaces, Understanding the AIX Interface for HCON API, API error codes, Sample Flows 
of API Programs in Communications Programming Concepts. 
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IF—ELSE 


IF-ELSE Statement 

Purpose 
Provides a two-way alternative test for conditional execution of Logon Assist Feature (LAF) 
statements. 

Syntax 
IF (condition) t-statement [ELSE f-statemenf| 

Description 
The IF-ELSE statement provides a two-way alternative test for conditional execution of LAF 
statements. The IF-ELSE statement is one of the script statements in the LAF language 
that are used to compose a LAF script. 

Expressions 
condition Condition to be evaluated 
t-statement Statement performed if condition evaluates true 
f—statement Statement performed if condition evaluates false 

Example 


The statements below search for a pattern. If a match is found, PA2 is sent to the host and a 
WAIT statement is executed, else the program exists with a return code of three (3). 


IF (MATCH)DO 
SEND(PA2); 
WAIT(1); 
END; 

ELSE 
EXIT(3); 


Implementation Specifics 
The IF-ELSE statement is part of the Logon Assist Feature of the AIX 3270 Host 
Connection Program/6000 (HCON). . 


Related Information 
How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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MATCH Statement 


Purpose 
Searches for a pattern in the current presentation space. 


Syntax 
MATCH(rownum,co/inum, string|ARG(N)); 


Description 
The Logon Assist Feature (LAF) MATCH statement searches for a pattern in the current 
presentation space. The presentation space is the characters that appear on a terminal 
display. The MATCH statement searches without waiting for receipt of data from the host. 
The MATCH statement is one of the script statements in the LAF language that are used to 
compose a LAF script. 


The special variable MATCH is set to 0 (zero) if the operation is not successful and to 1 
(one) if the operation is successful . If the search is successful, the special variables ROW 
and COL are set to reflect the location of the beginning of the match in the presentation 
space. 


Note: The WAIT statement can be used before MATCHAT (or MATCH) to control the time 
delay to receive data from the host before searching the presentation space. 


Parameters 
rownum Specifies the row number in the presentation space at which to 
begin the search for the pattern. 


colnum Specifies the column number in the presentation space to begin 
searching for the pattern. 


string Contains the string pattern to be used in the search. 


ARG(N) Contains the string pattern that is the Nth argument in the LAF 
logon ID string and should be used in the search. 


Example 
The MATCH statement searches the entire presentation space for the string MORE starting at 
row 24, column 1. 


MATCH(24,1,"”MORE” ); 
Implementation Specifics 


The MATCH statement is part of the Logon Assist Feature of the AIX 3270 Host Connection 
Program/6000 (HCON). 


Related Information 
How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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MATCHAT 


MATCHAT Statement 


Purpose 
Searches for a pattern in the current presentation space. 


Syntax 
MATCHAT(rownum,colnum,string| ARG(N)); 


Description 
The MATCHAT LAF statement is very similar to the MATCH statement. It searches for a 
pattern in the current presentation space without waiting for receipt of data from the host. 
The search is successful only if a match is found in the presentation space beginning at the 
specified position. The MATCHAT statement is one of the script statements in the LAF 
language that are used to compose a LAF script. 


lf a MATCHAT search operation is successful, ROW and COL are always set equal to 
rownum and colnum. The special variable MATCHis set to 0 (zero), if the operation is not 
successful and to 1 (one) for successful completion. 


Note: The WAIT statement can be used before MATCHAT (or MATCH) to control the time 
delay to receive data from the host before searching the presentation space. 


Parameters 
rownum Specifies the row number in the presentation space to begin the 
search for the pattern. 


colnum Specifies the column number in the presentation space at which to 
search for the pattern. 


string Contains the string pattern to be used in the search 


ARG(N) Contains the string pattern that is the Nth argument in the LAF 
logon ID string and should be used in the search. 


Example 
The MATCHAT statement searches for VM/370?0NLINE string starting at row 1, column 1: 
MATCHAT(1,1,’'VM/370?0NLINE’ ); 

implementation Specifics 


The MATCHAT statement is part of the Logon Assist Feature of the AlX 3270 Host 
Connection Program/6000 (HCON). 


Related Information 
The MATCH statement and RECEIVE statement. 


How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 
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NODEBUG Statement 


Purpose 

Disables debugging messages in a LAF script. 
Syntax 

NODEBUG; 
Description 


The NODEBUG statement turns off the generation of run—time debugging messages. The 
NODEBUG statement is one of the script statements in the LAF language that are used to 
compose a LAF script. 


Implementation Specifics 
The NODEBUG statement is part of the Logon Assist Feature of the AIX 3270 Host 
Connection Program/6000 (HCON). 


Related Information 
How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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RECEIVE 


RECEIVE Statement 


Purpose 
Waits for data to be received from the host and then searches the presentation space for a 
pattern. 


Syntax 
RECEIVE(rownum,colnum, string | ARG(N)); 


Description 
The RECEIVE statement waits 15 seconds or until data is received from the host and then 
searches the presentation space for a pattern. The RECEIVE statement is one of the script 
statements in the LAF language that are used to compose a LAF script. 


The special variable MATCH is set to 0 (zero), if the RECEIVE operation is not successful, 
and to 1 if the operation is successful. If the search is successful, the special variables ROW 
and COL are set to reflect the location of the beginning of the match in the presentation 
space. 


Parameters 


rownum Specifies the row number in the presentation space at which to begin the 
search for the pattern. 


colnum Specifies the column number in the presentation space at which to begin 
the search for the pattern. 


string Specifies a text string. 


ARG(N) Contains the string pattern which is the Nth argument in the LAF logon ID 
string and should be used in the search. 


Example 
The RECEIVE statement searches for MORE..., starting in row 25, column 75: 


RECEIVE(25,75,'MORE...’); 


Note: The RECEIVE statement waits up to 15 seconds to receive data from the host before 
searching the presentation space, but the MATCH and MATCHAT statements search 
immediately. The WAIT statement can be used in combination with MATCH and 
MATCHAT to control the time delay to receive data from the host. 


Implementation Specifics 


The RECEIVE statement is part of the Logon Assist Feature of the AIX 3270 Host 
Connection Program/6000 (HCON). 
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Related Information 
The MATCHAT statement and WAIT statement. 


How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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RECVAT 


RECVAT Statement 


Purpose 


Syntax 


Waits for data to be received from the host and then searches the presentation space for a 
pattern. 


RECVAT(rownum,colnum, string | ARG(N)); 


Description 


The RECVAT statement is very similar to the RECEIVE statement. It waits for data to be 
received from the host and then searches the presentation space for a pattern. The search 
is successful only if a match is found in the presentation space beginning at the specified 
position. The RECVAT statement is one of the script statements in the LAF language that 
are used to compose a LAF script. 


The special variable MATCH is set to 0 (zero) if the search is not successful and to 1 if the 
search is successful. If the search is successful, the special variables ROW and COL are set 
to indicate the location of the beginning of the match in the presentation space. Unlike the 
RECEIVE statement, if a RECVAT statement is successful, ROW and COL are always set 
equal to the rownum and co/lnum parameters, respectively. 


Parameters 


Example 


rownum Specifies the row number in the presentation space at which to begin the 
search for the pattern. 


colnum Specifies the column number in the presentation space at which to begin 
the search for the pattern. 


string Contains the string pattern to be used in the search 


ARG(N) Contains the string pattern which is the Nth argument in the LAF logon ID 
string and should be used in the search. 


The RECVAT statement searches for the string passed in the fifth token of the logon ID 
string. The search begins at row 3, column 1: 


RECVAT(3,1,ARG(4)); 


Implementation Specifics 


The RECVAT statement is part of the Logon Assist Feature of the AlX 3270 Host 
Connection Program/6000 (HCON). 


Related Information 


How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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REPEAT—UNTIL Statement 


Purpose 
Executes LAF script subject statement until the tested condition is found to be true. 
Syntax 
REPEAT statemenlist UNTIL (condition); 
Description 
The REPEAT—-UNTIL statement executes the subject statement until the tested condition is 
found to be true. 
Expressions 
statementlist Statement or statements to be executed until condition is true. 
condition Condition that halts execution of REPEAT—UNTIL loop,when true. 
Example 


The following REPEAT—UNTIL statement causes the WAIT statement to continue to execute 
until the TIMEOUT flag is set: 


REPEAT 
WAIT(2); 
UNTIL (TIMEOUT) ; 


Implementation Specifics 
The REPEAT-UNTIL statement is part of the Logon Assist Feature of the AIX 3270 Host 
Connection Program/6000 (HCON). 


Related Information 


How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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SELECT 


SELECT Statement 
Purpose 
Provides a multiple alternative test for conditional execution of Logon Assist Feature (LAF) 
statements. 
Syntax 
SELECT; WHEN-clause [OTHERWISE-c/ause] END; 
WHEN (condition) statement 
OTHERWISE statement 
Description 


The SELECT statement provides a multiple alternative test for conditional execution of LAF 
statements. The SELECT statement is one of the script statements in the LAF language 
that are used to compose a LAF script. 


Reserved Words 
WHEN-—clause Evaluates each statement in the WHEN clause until a true 
condition is found. The statement in the WHEN clause is 
then executed and control passes to the next statement 
following the SELECT statement. There may be multiple 
WHEN clauses in a SELECT statement. 


OTHERWISE-c/ause Executed only if none of the WHEN clauses is true. 
Expressions 
Condition A condition, when true, causes the statement in the WHEN clause to be 
executed. 
Statement Statement to execute. 


lf there is no OTHERWISE clause and none of the WHEN clauses are true, the SELECT 
statement does nothing. 


Example 
These statements check for the ENTER*PASSWORD: string starting at row 1, column 1 until a 
timeout occurs. If the timeout occurs the routine exits with a return code of three (3). 


REPEAT 
DO; 
MATCHAT(1,1,’ENTER*PASSWORD:’ ); 
SELECT; 
WHEN(NOT MATCH) WAIT(2); 
WHEN(TIMEOUT) EXIT(3); 
END; 
END; 
UNTIL(MATCH) ; 


Implementation Specifics 


The SELECT statement is part of the Logon Assist Feature of the AIX 3270 Host Connection 
Program/6000 (HCON). 
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Related Information 
How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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SEND 


SEND Statement 


Purpose 
Sends a string of keys to the emulator and from there to the host. 


Syntax 
SEND(string | keydef | UID | PW| ARG(N)); 


Description 
The SEND statement sends a string of keys to an emulator and from there to the host. 
e Ifthe string parameter is coded, that string is sent to the host. 
e Ifthe keydef parameter is coded, that special key is sent to the host. 


e \f any one or more of the U/D, PW, or ARG(N) parameters are coded, they are passed as 
parameters to the LAF script and sent as strings to the host. 


The SEND statement is one of the script statements in the LAF language that are used to 
compose a LAF script. 


Parameters 
string Specifies a text string 


keydef Contains the string or key definition to be sent to the host. 
UID Specifies the host user ID. 
PW Specifies the password associated with the UID. 


ARG(N) Contains the string pattern which is the Nth argument in the LAF logon 
ID string and should be used in the search. 


Example 
The SEND statement sends the Enter key to the host: 
SEND (ENTER) ; 

Implementation Specifics 


The SEND statement is part of the Logon Assist Feature of the in AIX 3270 Host Connection 
Program/6000 (HCON). 
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START Statement 
Purpose 
Begins a Logon Assist Feature (LAF) script. 
Syntax 
START [string] 
Description 
The START statement begins a LAF script. The START statement is one of the script 
statements in the LAF language that are used to compose a LAF script. 
Parameters 
string Defines the name of the generated C function. If a name is not 
supplied, the g32_logon script is used. Each script must have one 
START statement, which must be the first statement in the script. 
Example 


The following START statement specifies the start of a new script labeled g32_logoff: 
START “g32_logoff”; 


Implementation Specifics 


The START statement is part of the Logon Assist Feature of the AIX 3270 Host Connection 
Program/6000. 


Related Information 


How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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WAIT 


WAIT Statement 


Purpose 
Causes the Logon Assist Feature (LAF) script to wait until data is received from the host or 
until the specified number of seconds has elapsed. 


Syntax 
WAIT(numben; 


Description 
The WAIT statement causes the LAF script to wait until data is received from the host or 
until the specified number of seconds has elapsed. The special variable TIMEOUT is set to 0 
(zero) if data is received from the host and to one (1) if the specified time has elapsed. 


Note: Use of the WAIT statement at the beginning of a script is not a good practice as the 
initial data from the host is received immediately. 


The WAIT statement is one of the script statements in the LAF language that are used to 
compose a LAF script. 


Expression 


number Specifies in seconds, the amount of time to wait. A negative value indicates 
that the WAIT statement only returns when data is received from the host. A 
value of 0 indicates that the WAIT statement returns immediately. 


Example 
This statement executes a one—second wait if a match is not found: 


IF(NOT MATCH) WAIT(1); 


Due to variability in the amount of time it may take to log on, the WAIT statement should be 
used sparingly outside of loops. REPEAT-UNTIL loops are another means of waiting for an 
event to occur at the host. 


The following loop can be used instead of a WAIT statement: 


REPEAT 
DO 
MATCH(1,1,’MORE’ ); 
IF (MATCH) DO; 
SEND(PA2); 
END; 
MATCH(1,1,’'R; TT’); 
IF (NOT MATCH) DO 
WAIT (2); 
IF (TIMEOUT) 
BREAK; 
END; 
END; 
UNTIL (MATCH); 


Implementation Specifics 


The WAIT statement is part of the Logon Assist Feature of the AIX 3270 Host Connection 
Program/6000 (HCON). 
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Related Information 
How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. . 


HCON Overview for Programming in Communications Programming Concepts. 
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WHILE 


WHILE Statement 
Purpose 
Executes a Logon Assist Feature (LAF) script subject statement. 
Syntax 
WHILE (condition) statement 
Description 
The WHILE statement executes a subject statement as long as the tested condition remains 
true. The WHILE statement is one of the script statements in the LAF language that are 
used to compose a LAF script. 
Expression 
condition A condition may be any of the following: 
MATCH 
TIMEOUT 
RECOVERY 
ROW <comparison operator> <number> 
COL <comparison operator> <number> 
<condition> AND <condition> 
<condition> OR <condition> 
NOT «condition> 
Example 


The following example is a condition in the LAF language. Conditions are used in the 
WHILE, REPEAT—UNTIL, IF—ELSE, and SELECT statements. 


WHILE(NOT TIMEOUT) WAIT(2); 
The WHILE statement continues to execute until the TIMEOUT flag is set. 


Implementation Specifics 


The WHILE statement is part of the Logon Assist Feature of the AIX 3270 Host Connection 
Program/6000 (HCON). 


Related Information 


How To Use a Logon Assist Feature Script, Understanding the Logon Assist Feature (LAF) 
in Communications Programming Concepts. 


HCON Overview for Programming in Communications Programming Concepts. 
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Data Link Controls 


Data Link Controls 3-1 


3-2 Base Operating System Reference 


close 


close Subroutine Interface for Data Link Control (dic) Devices 


Purpose 

Closes the GDLC device manager using a file descriptor. 

Syntax 
int close (fildes); 
int fildes; 

Description | 
The close subroutine disables a generic data link control (GDLC) channel. If this is the last 
channel to close on a port, the GDLC device manager is reset to an idle state on that port 
and the communications device handler is closed. 

Parameter 


fildes Specifies the file descriptor of the GDLC being closed. 


Return Values 
Upon successful completion, the close subroutine returns a value of 0 (zero). 


If an error occurs, a value of —1 is returned with one of the following error numbers available 
using errno, as defined in the errno.h header file: 


EBADF Bad file number 


implementation Specifics 
This close subroutine interface is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The close subroutine. 
open Subroutine Interface for Data Link Control (dic) Devices 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


Data Link Controls 3-3 


dicclose 


dicclose Entry Point of the GDLC Device Manager 


Purpose 
Entry point to close a GDLC channel. 
Syntax 
#include <sys/device.h> 
int dicclose (devno, chan, ext) 
dev_t devno; 
int chan, ext; 
Note: The dic prefix is replaced with the 3-digit prefix for the specific GDLC device 
manager being closed. 
Description 
The dicclose routine is called when a user’s application program invokes the close 
subroutine or when a kernel user calls the fp_close kernel service. This routine disables a 
generic data link control (GDLC) channel for the user. If this is the last channel to close on 
the port, the GDLC device manager issues a close to the network device handler and 
deletes the kernel process that serviced device handler events on behalf of the user. 
Parameters 


devno Indicates major and minor device numbers. This is a dev_t device number 
that specifies both the major and minor device numbers of the GDLC device 
manager. There is one dev_t device number for each type of GDLC, such 
as Ethernet, Token-Ring, or SDLC. 


chan Specifies the channel ID assigned by GDLC in the dicmpx routine at open 
time. 

ext Specifies the extended subroutine parameter. This parameter is ignored by 
GDLC. 


Return Values 


Upon successful completion, this service returns a value of 0 (zero). 
If an error occurs, the following error value is returned, as defined in the errno.h header file: 


EBADF Bad file number. 


Implementation Specifics 
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This dicclose entry point of the GDLC is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Base Operating System Reference 


dicclose 


Related Information 
The ddclose device entry point. 


The fp_close kernel service. 

The close subroutine. 

dicopen Entry Point of the GDLC Device Manager. 
dicmpx Entry Point of the GDLC Device Manager. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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dicconfig Entry Point of the GDLC Device Manager 


Purpose 
Entry point to configure the GDLC device manager. 


Syntax 
#include <sys/uio.h> 
#include <sys/device.h> 


int dicconfig (devno, op, uiop) 
dev_t devno; 

int op; 

struct uio *uiop; 


Note: The dic prefix is replaced with the 3-digit prefix for the specific GDLC device 
manager being configured. 


Description 
The dieconfig routine is called during the kernel startup procedures to initialize the GDLC 
device manager with its device information. This routine is also called by the operating 
system when the GDLC is being terminated or queried for vital product data. 


Parameters 


devno Indicates major and minor device numbers. This is a dev_t device number 
that specifies both the major and minor device numbers of the GDLC device 
manager. There is one dev_t device number for each type of GDLC, such 
as Ethernet, Token-Ring, or SDLC. 


op Specifies the operation code that indicates the function to be performed: 
INIT Initializes the GDLC device manager. 
TERM Terminates the GDLC device manager. 
QVPD Queries GDLC vital product data. This operation code is 
optional. 
ulop A pointer to the uio structure specifying the location and length of the 


caller’s data area for the INIT and QVPD operation codes. No data areas 
are specifically defined for GDLC, but DLC’s may define the data areas for a 
particular network. 


Return Values 
Upon successful completion, this service returns a value of 0 (zero). 


If an error occurs, one of the following error values is returned, as defined in the errno.h 


header file: 

EINVAL Invalid value 

ENODEV No such device handler 

EFAULT Kernel service, such as uiomove or devswadd, has failed. 
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dicconfig 


Implementation Specifics 


This dleconfig entry point of the GDLC is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
Theddconfig device entry point. 


The uiomove kernel service. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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dicioctl Entry Point of the GDLC Device Manager 


Purpose 
Entry point to issue specific commands to GDLC. 
Syntax 
#include <sys/device.h> 
#include <sys/gdlextcb.h> 
int dicioctl (devno, op, arg, devflag, chan, ext) 
dev_t devno; 
ulong_t devflag; 
int op, arg, chan, ext; 
Note: The dic prefix is replaced with the 3-digit prefix for the specific GDLC device 
manager being controlled. 
Description 
The dicioctl routine is called when a user’s application program invokes the ioctl subroutine 
or when a kernel user calls the fp_ioctl kernel service. The dicioctl routine decodes 
commands for special functions in the generic data link contro! (GDLC). 
Parameters 


devno Indicates major and minor device numbers. This is a dev_t device number 
that specifies both the major and minor device numbers of the GDLC device 
manager. There is one dev_t device number for each type of GDLC, such 
as Ethernet, Token-Ring, or SDLC. 


op Specifies the parameter from the subroutine that specifies the operation to 
be performed. loct! Operations for DLC provides a listing of all possible 
operators. 

arg Indicates the parameter from the subroutine that specifies the address of a 


parameter block. Parameter Blocks by ioct! Operation for DLC provides a 
listing of all possible arguments. 


devilag Specifies the flag word with the following flags defined: 


DKERNEL Entry point called by kernel routine using the fp_open 
kernel service. This indicates that the arg parameter points 
to kernel space. 


DREAD Open for reading. This flag is ignored. 

DWRITE Open for writing. This flag is ignored. 

DAPPEND Open for appending. This flag is ignored. 

DNDELAY Device open in nonblocking mode. This flag is ignored. 


chan Specifies the channel ID assigned by GDLC in the dicmpx routine at open 
time. 
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ext Specifies the extended subroutine parameter. This parameter is ignored by 
GDLC. 


Return Values 
Upon successful completion, this service returns a value of 0. 


If an error occurs, one of the following error values is returned, as defined in the errno.h 


header file: 

EBADF Bad file number 

EINVAL Invalid value 

ENOMEM Not enough resources to satisfy the ioctl subroutine. 


Implementation Specifics 


This dicioctl entry point of the GDLC is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The ddioct! device entry point. 
The fp_ioctl kernel service, fo_open kernel service. 
The ioct! subroutine. 
dicmpx Entry Point of the GDLC Device Manager. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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dicmpx Entry Point of the GDLC Device Manager 


Purpose | 
Entry point to decode the device handlers special file name appended to the open call. 
Syntax 
#include <sys/device.h> 
int dicmpx (devno, chanp, channame) 
dev_t devno; 
int *chanp; 
char *channame; 
Note: The dic prefix is replaced with the 3-digit prefix for the specific GDLC device 
manager being opened. 
Description 
The dicmpx routine is called by the operating system when a generic data link control 
(GDLC) channel is being allocated. This routine decodes the name of the device handler 
that is appended to the end of the GDLC’s special file name at open time. GDLC allocates | 
the channel and returns the value in the chanp parameter. 
This routine is also called following a close subroutine to deallocate the channel. In this 
case the chanp parameter is passed to GDLC in order to identify the channel being 
deallocated. Since GDLC allocates a new channel for each open subroutine, there is a 
dicmpx routine following each call to the dicclose routine. 
Parameters 


devno Indicates major and minor device numbers. This is a dev_t device number 
that specifies both the major and minor device numbers of the GDLC device 
manager. There is one dev_t device number for each type of GDLC, such 
as Ethernet, Token-Ring, or SDLC. 


chanp Specifies the channel ID returned if a valid path name exists for the device 
handler, and the openflag is set. If no channel ID is allocated, this field is 
set to a value of -1 by GDLC. 


channame Specifies a pointer to the appended path name (path name extension) of the 
device handler that is used by GDLC to attach to the network. If this is 
NULL, the channel is to be deallocated. 


Return Values 
Upon successful completion, this service returns a value of 0 (zero). 


lf an error occurs, one of the following error values is returned, as defined in the errno.h 


header file: 
EBADF Bad file number. 
EINVAL Invalid value. 
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Implementation Specifics 


This dicmpx entry point of the GDLC is part of the device manager Data Link Control in - 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The ddmpx device entry point. 
The close subroutine, open subroutine. 
dicclose Entry Point of the GDLC Device Manager. 
dicopen Entry Point fo the GDLC Device Manager. 
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dicopen Entry Point of the GDLC Device Manager 


Purpose 
Entry point to open a GDLC channel. 
Syntax 
#include <sys/device.h> 
#include <sys/gdlextcb.h> 
int dlcopen (devno, devflag, chan, ext) 
dev_t devno; 
ulong_t devfiag; 
int chan, ext; 
Note: The dlc prefix is replaced with the 3-digit prefix for the specific GDLC device 
manager being opened. 
Description 
The dicopen routine is called when a user’s application program invokes the open or 
openx subroutine, or when a kernel user calls the fp_open kernel service. The generic data 
link control (GDLC) device manager opens the specified communications device handler and 
creates a kernel process to catch posted events from that port. Additional opens to the same 
port share both the device handler open and the GDLC kernel process created on the 
Original open. 
Note: It may be more advantageous to handle the actual device handler open and 
kernel process creation in the dlcmpx routine. This is left as a specific DLC’s option. 
Parameters 


devno Indicates major and minor device numbers. This is a dev_t device number 
that specifies both the major and minor device numbers of the GDLC device 
manager. There is one dev_t device number for each type of GDLC, such 
as Ethernet, Token-Ring, or SDLC. 


devilag Specifies the flag word with the following flags defined: 


DKERNEL Entry point called by kernel routine using the fp_open 
kernel service. All command extensions and ioctl 
arguments will be in kernel space. 


DREAD Open for reading. This flag is ignored. 

DWRITE Open for writing. This flag is ignored. 

DAPPEND Open for appending. This flag is ignored. 

DNDELAY Device open in non-blocking mode. This flag is ignored. 
chan Specifies the channel ID assigned by GDLC in the dilcempx routine. 


ext Specifies the extended subroutine parameter. This is a pointer to the 
dic_open_ext extended I/O structure for open subroutine. 
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Return Values 
Upon successful completion, this service returns a value of 0 (zero). 


If an error occurs, one of the following error values is returned, as defined in the errno.h 


header file: 

ECHILD Cannot create a kernel process. 

EINVAL Invalid value. 

ENODEV No such device handler. 

ENOMEM Not enough resources to satisfy the open subroutine. 
EFAULT Kernel service, such as copyin or initp, failed. 


Implementation Specifics 


This dicopen entry point of the GDLC is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The ddopen device entry point. 
The open, openx subroutine. 
Thefp_open kernel service, copyin kernel service, initp kernel service. 
dicclose Entry Point of the GDLC Device Manager. 
dicmpx Entry Point of the GDLC Device Manager. 
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dicread Entry Point of the GDLC Device Manager 


Purpose 
Entry point to read receive data from GDLC. 
Syntax 
#include <sys/device.h> 
#include <sys/gdlextcb.h> 
int dlcread (devno, uiop, chan, ext) 
dev_t devno; 
struct uio *uiop; 
int chan, ext; 
Note: The dic prefix is replaced with the 3-digit prefix for the specific GDLC device 
manager being read. 
Description 
The dicread routine is called when a user’s application program invokes the readx 
subroutine. Kernel users do not call an fp_read kernel service. All receive data is returned to 
the user in the same order as received. The type of data that was read is indicated, as well 
as the service access point (SAP) and link station (LS) identifiers. 
The following fields in the uio and iov structures are used to control the read-data transfer 
operation: 
uio_iov Points to an iovec structure. 
uio_iovent Number of elements in the iovec structure. This must be set to a 
value of 1. Vectored read operations are not supported. 
uio_ offset The file offset established by a previous fp_Iseek subroutine. This 
field is ignored by generic data link control (GDLC). 
uio_segflag Indicates whether the data area is in application or kernel space. 
This is set to the UlO_USERSPACE value by the file 1/O subsystem 
to indicate application space. 
uio_fmode Contains the value of the file mode set with the open applications 
subroutine to GDLC. 
uio_resid This field is initially the total byte count of the receive data area. 
GDLC decrements this count for each packet byte received using 
the uiomove subroutine. 
iovec structure A structure that contains the starting address and length of the 
received data. 
iov_base A variable in the tovec structure where GDLC writes the address of 
the received data. 
iov_len A variable in the iovec structure that contains the byte length of the 
data. 
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Parameters 

devno Indicates major and minor device numbers. This is a dev_t device number 
that specifies both the major and minor device numbers of the GDLC device 
manager. There is one dev_t device number for each type of GDLC, such 
as Ethernet, Token-Ring, or SDLC. 

ulop Points to the uio structure containing the read parameters. 

chan Specifies the channel ID assigned by GDLC in the dicmpx routine at open 
time. 

ext Specifies the extended subroutine parameter. This is a pointer to the 


extended I/O structure. The argument to this parameter must always be in 
the application space. DLC Extended Parameters for read Subroutine 
provides more information on this parameter. 


Return Values 
Reads that are successful and reads that must be truncated due to limited user data space 
each return a value of 0. If more data is received from the media than will fit into the 
application data area, the DLC_OFLO value indicator is set in the command extension area 
(dic_io_ext) to indicate that the read is truncated. All excess data is lost. 


If other errors occur, one of the following error values is returned, as defined in the errno.h 


header file: 

EBADF Bad file number. 

EINTR A signal interrupted the subroutine before it received data. 
EINVAL Invalid value. 

ENOMEM Not enough resources to satisfy the read. 


Implementation Specifics 


This dicread entry point of the GDLC is part of the device manager Data Link Control in. 
BOS Extensions 2. , 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The ddread device entry point. 
The fp_read kernel service. 
The readx subroutine, fp_Ilseek subroutine, uiomove subroutine, open subroutine. 
dicmpx Entry Point of the GDLC Device Manager. 
DLC Extended Parameters for read Subroutine. 
dicwrite Entry Point of the GDLC Device Manager. 
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dicselect Entry Point of the GDLC Device Manager 


Purpose 


Entry point to select for asynchronous criteria from GDLC, such as receive data completion 
and exception conditions. 


Syntax 
#include <sys/device.h> 
#include <sys/gdlextcb.h> 


int dicselect (devno, events, reventp, chan) 
dev_t devno; 

ushort_t events; 

ushort_t *reventp; 

int chan; 


Note: The dic prefix is replaced with the three-digit prefix for the specific GDLC device 
manager being selected. 


Description | 
The dicselect routine is called when a user’s application program invokes a select or poll 
subroutine. This allows the user to select receive data or exception conditions. The 
DPOLLOUT write-availability criteria is not supported. If no results are available at the time 
of a select subroutine, the user process is put to sleep until an event occurs. 


If one or more events specified in the events parameter are true, the dicselect routine 
updates the returned events parameter (passed by reference), reventp, by setting the 
corresponding event bits that indicate which events are currently true. 


If none of the requested events are true, the dicselect routine sets the returned events 
parameter to a value of 0 (passed by reference using the reventp parameter) and checks the 
DPOLLSYNC flag in the events parameter. If this flag is true, the routine returns because 
the event request was a synchronous request. If the DPOLLSYNC flag is false, an internal 
flag is set for each event requested in the events parameter. 


When one or more of the requested events become true, generic data link control (GDLC) 
issues the selnotify kernel service to notify the kernel that a requested event or events 
have become true. The internal flag indicating that the event was being requested is then 
reset to prevent renotification of the event. 


If the port in use is in a closed state, implying that the requested event or events can never 
be satisfied, GDLC sets the returned events flags to a value of 1 for each event that can 
never be satisfied. This is done so that the select or poll subroutine does not wait 
indefinitely. 


Kernel users do not call an fp_select kernel service since their receive data and exception 
notification functions are called directly by GDLC. The DLC Extended Parameters for open 
Subroutine details how these function handlers are specified. 


Parameters 


devno Indicates major and minor device numbers. This is a dev_t device number 
that specifies both the major and minor device numbers of the GDLC device 
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manager. There is one dev_t device number for each type of GDLC, such 
as Ethernet, Token-Ring, or SDLC. 


events Identifies the events that are to be checked. The following events are: 
DPOLLIN Read selection. 
DPOLLOUT. Write selection. This is not supported by GDLC. 
DPOLLPRI Exception selection. 
DPOLLSYNC This request is a synchronous request only. The 


routine should not perform a selnotify kernel service 
routine due to this request if the events occur later. 


reventp Identifies a returned events pointer. This is a parameter passed by 
reference to indicate which of the selected events are true at the time of the 
call. See the preceding events parameter for possible values. 


chan Specifies the channel ID assigned by GDLC in the dlcmpx routine at open 
time. 


Return Values 
Upon successful completion, this service returns a value of 0 (zero). 


If an error occurs, one of the following error numbers is returned, as defined in the errno.h 


header file: 

EBADF Bad file number. 

EINTR A signal interrupted the subroutine before it found any of the selected 
events. 

EINVAL The specified DPOLLOUT write selection is not supported. 


Implementation Specifics 
This dicselect entry point of the GDLC is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The ddselect device entry point. 
The select subroutine, poll subroutine. 
The fp_select kernel service. 
DLC Extended Parameters for open Subroutine. 
dicselect Entry Point of the GDLC Device Manager. 
dicmpx Entry Point of the GDLC Device Manager. 
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dicwrite Entry Point of the GDLC Device Manager 


Purpose 
Entry point to write transmit data to GDLC. 


Syntax 
#include <sys/uio.h> 
#include <sys/device.h> 


#include <sys/gdlextcb.h> 

int dlcewrite (devno, uiop, chan, ext) 
dev_t devno; 

struct uio *uiop; 

int chan, ext; 


Note: The dic prefix is replaced with the 3-digit prefix for the specific GDLC device 
manager being written. 


Description 
The dlewrite routine is called when a user’s application program invokes a writex 
subroutine or when a kernel user calls the fp_write kernel service. An extended write is 
used in order to specify the type of data being sent, as well as the service access point 
(SAP) and link station (LS) identifiers. 


The following fields in the uio and iov structures are used to control the write data transfer 
operation: 


uio_iov Points to an iovec structure. 


uio_iovent Number of elements in the iovec structure. This must be set to a value of 1 
for the kernel user, indicating that there is a single communications memory 
buffer (mbuf) chain associated with the write subroutine. 


uio_offset The file offset established by a previous fp_Iseek kernel service. This field 
is ignored by GDLC. 


uio_segflag Indicates whether the data area is in application or kernel space. This field 
is set to the UlO_USERSPACE value by the file I/O subsystem if the data 
area is in application space. The field must be set to the UIO_SYSSPACE 
value by the kernel user to indicate kernel space. 


uio_fmode Contains the value of the file mode set during an application open 


subroutine to GDLC or can be set directly during a kernel user’s fp_open 
kernel service to GDLC. 


uio_resid For application users this field is set to the total byte count of the transmit 
data area. For kernel users, GDLC ignores this field since the 
communications memory buffer (mbuf) also carries this information. 


iovec structure A structure that contains the starting address and length of the transmit. 
(See the iov_base field and iov_len field.) 
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iov_base A variable in the iovec structure where GDLC gets the address of the 


application user's transmit data area or the address of the kernel user’s 
transmit mbuf. 


iov_len A variable in the iovec structure that contains the byte length of the 
application user’s transmit data area. This variable is ignored by GDLC for 
kernel users, since the transmit mbuf contains a length field. 


Parameters 

devno Indicates major and minor device numbers. This is a dev_t device number 
that specifies both the major and minor device numbers of the GDLC device 
manager. There is one dev_t device number for each type of GDLC, such 
as Ethernet, Token-Ring, or SDLC. 

ulop Points to the uio structure containing the write parameters. 

chan Specifies the channel ID assigned by GDLC in the dicmpx routine at open 
time. 

ext Specifies the extended subroutine parameter. This is a pointer to the 


~ extended I/O structure. This data must be in the application space if the 
iov_fmode field indicates an application subroutine or in the kernel space if 
the iov_fmode field indicates a kernel subroutine. DLC Extended 
Parameters for Write provides more information on this parameter. 


Return Values 
Upon successful completion, this service returns a value of 0 (zero). 


If an error occurs, one of the following error values is returned, as defined in the errno.h 


header file: 

EAGAIN Transmit is temporarily blocked, and a sleep cannot be issued. 

EBADF Bad file number (application). 

EINVAL Invalid value, such as too much data for a single packet. 

ENOMEM Not enough resources to satisfy the write subroutine, such as a lack of 
communications memory buffers (mbufs). 

ENXIO Invalid file pointer (kernel). 


Implementation Specifics 


This dicwrite entry point of the GDLC is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 
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Related Information 
The ddwrite device entry point. 


dicmpx Entry Point of the GDLC Device Manager. 

The writex subroutine, open subroutine. 

The fp_write kernel service, fp_lseek kernel service, fp_open kernel service. 
dicread Entry Point of the GDLC Device Manage. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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fp_close Kernel Service for Data Link Control (DLC) Devices 


Purpose 
Allows kernel closes to the GDLC device manager using a file pointer. 


Syntax 
int fp_close (fo, ext); 
struct file *fp; 


Description 
The fp_close kernel service disables a generic data link control (GDLC) channel. If this is 
the last channel to close on a port, the GDLC device manager resets to an idle state on that 
port and the communications device handler is closed. 


Parameters 
fp Specifies the file pointer of the GDLC being closed. 


ext Specifies the extension parameter. This parameter is ignored by GDLC. 


Return Values 
Upon successful completion, this service returns a value of 0 (zero). 


If an error occurs, the following error value is returned, as defined in the errno.h header file: 


ENXIO Invalid file pointer. 


Implementation Specifics 
This fp_close kernel service is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The fp_close kernel service. 
fp_open Kernel Service for Data Link Control (DLC) Devices. 
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fp_ioctl Kernel Service for Data Link Control (DLC) Devices 


Purpose 
Transfers special commands from the kernel to GDLC using a file pointer. 


Syntax 
#include <sys/gdlextcb.h> 
#include <fentl.h> 


int fp_ioctl (fo, cmd, arg, ext) 
struct file *fp; 

unsigned int cmd; 

caddr_t arg; 

int ext; 


Description 

Various generic data link control (GDLC) functions can be initiated using the fp_ioctl kernel 
service, such as changing configuration parameters, contacting the remote, and testing a 
link. Most of these operations can be completed before returning to the user synchronously. 
Some operations take longer, so asynchronous results are returned some time later using 
the exception function handler. GDLC calls the kernel user’s exception handler to complete 
these results. For more information on the functions that can be initiated using the fp_ioctl 
kernel service, see loctl Operations (op) DLC and Parameter Blocks by Operation for DLC. 


Note: The DLC_GET_EXCEP ioctl! command operation is not used since all exception 
conditions are passed to the kernel user through the exception handler. 


Parameters 
fp Specifies the file pointer of the target GDLC. 


cmd Specifies the operation to be performed by GDLC. For a listing of all 
possible operators, see loctl Operations (op) for DLC. 


arg Specifies the address of the parameter block. The argument for this 


parameter must be in the kernel space. For a listing of possible values, see 
Parameters Blocks by Operations for DLC. 


ext Specifies the extension parameter. This parameter is ignored by GDLC. 


Return Values 
Upon successful completion, the fp_ioct! kernel! service returns a value of 0 (zero). 


If an error occurs, one of the following error values is returned, as defined in the errno.h 


header file: 

ENXIO Invalid file pointer 

EINVAL Invalid value 

ENOMEM Not enough resources to satisfy the ioctl subroutine. 
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Implementation Specifics 


This fp_ioctl kernel service is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The fp_ioctl kernel service. 
The ioctl subroutine. 
The ioctl subroutine. 
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fp_ open Kernel Service for Data Link Control (DLC) Devices 


Purpose 


Syntax 


Allows kernel opens to the GDLC device manager by its device name. 


#include <sys/gdlextcb.h> 
#include <fentl.h> 


fp_open (path, oflags, cmode, ext, segflag fpp) 
char path; 

unsigned int oflags; 

unsigned int cmode; 

int ext; 

unsigned int segflag; 

struct file **fop; 


Description 


The fp_open kernel service allows the kernel user to open a generic data link control 
(GDLC) device manager by specifying the special file names of both the DLC and the 
communications device handler. Since the GDLC device manager is multiplexed, more than 
one process can open it (or the same process multiple times) and still have unique channel 
identifications. 


Each open carries the communications device handler’s special file name so that the DLC 
knows which port to transfer data on. 


The kernel user must also provide functional entry addresses in order to obtain receive data 
and exception conditions. Using Special Kernel Services provides related information. 


Parameters 
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path Consists of a character string containing the /dev special file name of the 
GDLC device manager, with the name of the communications device 
handler appended. The format is shown in the following example: 


/dev/dicether/ent0o 


oflags Specifies a value to set the file status flag. The GDLC device manager 
ignores all but the following values: 


O_RDWR Open for reading and writing. This must be set for GDLC or 
the open will fail. 


O_NDELAY, O_NONBLOCK 


Subsequent writes return immediately if no resources are 
available. The calling process is not put to sleep. 


cmode Specifies the O_CREAT mode parameter. This is ignored by GDLC. 


ext Specifies the extended kernel service parameter. This is a pointer to the 
dic_open_ext extended I/O structure for open subroutines. The argument 
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for this parameter must be in the kernel space. DLC Extended Parameters 
for open Subroutine provides more information on the extension parameter. 


segflag Specifies the segment flag indicating where the path parameter is located: 
FP_SYS The path parameter is stored in kernel memory. 
FP_USR The path parameter is stored in application memory. 


fpp Specifies the returned file pointer. This parameter is passed by reference 


and updated by the file I/O subsystem to be the file pointer for this open 
subroutine. 


Return Values 


Upon successful completion, this service returns a value of 0 (zero) and a valid file pointer in 
the fp parameter. 


If an error occurs, one of the following error values is returned as defined in the errno.h 


header file: 

ECHILD Cannot create a kernel process. 
EINVAL invalid value. 

ENODEV No such device handler. 


ENOMEM Not enough resources to satisfy the open. 


EFAULT Kernel service, such as copyin or initp, has failed. 


Implementation Specifics 


This fp_open kernel service is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The fp_open kernel service, copyin kernel service, initp kernel service. 
fp_close Kernel Service for Data Link Control (DLC) Devices. 
DLC Extended Parameters for the open Subroutine. 
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fp_write Kernel Service for Data Link Control (DLC) Devices 


Purpose 
Allows kernel data to be sent using a file pointer. 


Syntax 
#include <sys/gdlextcb.h> 
#include <sys/fp_io.h> 


int fp_write (fo, buf, nbytes, ext, segflag, countp) 
struct file */p; 

char *buf, 

int nbytes; 

int ext; 

int segflag; 

int *countp; 


Description 
Four types of data can be sent to GDLC. Network data can be sent to a service access point 
(SAP), and normal, Exchange Identification (XID), or datagram data can be sent to a link 
station (LS). 


Kernel users pass a communications memory buffer (mbuf) directly to generic data link 
contro! (GDLC) on the fp_write kernel service. In this case, a uiomove kernel service is not 
required, and maximum performance can be achieved by merely passing the buffer pointer 
to GDLC. Each write buffer is required to have the proper buffer header information and 
enough space for the data link headers to be inserted. A write data offset is passed back to 
the kernel user at start LS completion for this purpose. 


All data must fit into a single packet for each write call. That is, GDLC does not separate the 
user’s write data area into multiple transmit packets. A maximum write data size is passed 
back to the user at DLC_ENABLE_SAP completion and at DLC_START_LS completion for 
this purpose. 


Normally, a write subroutine can be satisfied immediately by GDLC by completing the data 
link headers and sending the transmit packet down to the device handler. In some cases, 
however, transmit packets can be blocked by the particular protocol’s flow control or a 
resource outage. GDLC reacts to this differently, based on the system blocked/nonblocked 
file status flags (set by the file system and based on the O_NDELAY and O_NONBLOCKED 
values passed on the fp_open kernel service). Nonblocked write subroutines that cannot 
get enough resources to queue the communications memory buffer (mbuf) return an error 
indication. Blocked write subroutines put the calling process to sleep until the resources free 
up or an error occurs. 


Parameters 
fo Specifies file pointer returned from the fp_open kernel service. 


buf Points to a kernel mbuf. 


nbytes Contains the byte length of the write data. It is not necessary to set this field 
to the actual length of write data, however, since the mbuf contains a length 
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field. Instead, this field can be set to any non-negative value (generally set 
to 0 (zero)). 


ext Specifies the extended kernel service parameter. This is a pointer to the 
dic_io_ext extended |/O structure for writes. The argument for this 
parameter must be in the kernel space. For more information on this 
parameter, see DLC Extended Parameters for write Subroutine. 


segflag Specifies the segment flag indicating where the path parameter is located. 
The only valid value is: 
FP_SYS The path parameter is stored in kernel memory. 

countp Points to the location where a count of bytes actually written is to be 


returned (must be in kernel space). GDLC does not provide this information 
for a kernel user since mbufs are used, but the file system requires a valid 
address and writes a copy of the nbytes parameter to that location. 


Return Values 


Upon successful completion, this service returns a value of 0 (zero). 


If an error occurs, one of the following error values is returned, as defined in the errno.h 
header file: 


EAGAIN Transmit is temporarily blocked, and the calling process cannot be put to 
sleep. 

EINVAL Invalid argument, such as too much data for a single packet. 

ENXIO Invalid file pointer. 


implementation Specifics 


This fp_write kernel service is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 


The fp_write kernel service. 

The uiomove subroutine, fp_open kernel service. 
Parameter Blocks by ioctl Operation for DLC. 

DLC Extended Parameters for the write Subroutine. 
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ioctl Subroutine Interface for Data Link Control (DLC) Devices 


Purpose | 
Transfers special commands to GDLC using a file descriptor. 


Syntax 
#include <sys/ioctl.h> 
#include <sys/devinfo.h> 
#include <sys/gdiextcb.h> 
int ioctl (fildes, op, arg); 
int fildes; 
int op; 
char *arg; 

Description 
The ioctl subroutine initiates various generic data link control (GDLC) functions, such as 
changing configuration parameters, contacting a remote link, and testing a link. Most of 
these operations can be completed before returning to the user (synchronously). Since some 
operations take longer, asynchronous results are returned some time later using the 
exception condition notification. Application users can obtain these exceptions using the 
DLC_GET_EXCEP ioctl operation. For more information on the functions that can be 
initiated using the ioctl subroutine, see loctl Operations for DLC (op) and Parameter Blocks 
by Operations for DLC. 

Parameters 

- fildes Specifies the file descriptor of the target GDLC. 

op Specifies the operation to be performed by GDLC. For a listing of all 


possible operators, see loctl Operations. 


arg Specifies the address of the parameter block. For a listing of possible 
values, see Parameter Blocks by Operations for DLC. 


Return Values 
Upon successful completion, the ioctl subroutine returns a value of 0 (zero). 


If an error occurs, a value of —1 is returned with one of the following error numbers available 
using errno, as defined in the errno.h header file: 


EBADF Bad file number. 
EINVAL Invalid argument. 
ENOMEM Not enough resources to satisfy the ioctl subroutine. 


Implementation Specifics 


This ioctl subroutine interface is part of the device manager Data Link Control in BOS 
Extensions 2. 
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Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
loctl Operations (op) for DLC and Parameter Blocks by Operations for DLC . 


The ioctl subroutine. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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ioct! Subroutine Operations (op) for DLC 


Description 


GDLC supports the following ioctl command operations: 


#define DLC_ENABLE_SAP 
#define DLC _DISABLE_SAP 
#define DLC_START_LS 
#define DLC_HALT LS 
#define DLC_TRACE 
#define DLC CONTACT 
#define DLC_TEST 
#define DLC_ALTER 
#define DLC_QUERY_ SAP 
#define DLC_QUERY_LS 
#define DLC _ENTER_ LBUSY 
#define DLC EXIT _LBUSY 
#define DLC_ENTER_SHOLD 
#define DLC_EXIT_SHOLD 
#define DLC_GET_EXCEP 
#define DLC_ADD_GRP 
#define IOCINFO 


DLC_ADD_GRP 


DLC_ALTER 


DLC_CONTACT 


DLC_DISABLE_SAP 


DLC_ENABLE_ SAP 


DLC_ENTER_LBUSY 
DLC_ENTER_SHOLD 
DLC_EXIT_LBUSY 
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3 


ony vn Ws 


9 

10 

ta, 

12 

13 

14 

15 

16 
/* see /usr/include/sys/ioctl.h */ 


Add a group or multicast receive address to a port. This 
command allows additional address values to be filtered in 
receive as supported by the individual communication 
device handlers. See the device handler specifications to 
determine which address values are supported. 


Alters link station (LS) configuration. 


Contacts the remote LS. This ioctl operation does not 
complete processing before returning to the user. The 
DLC_CONTACT notification is returned asynchronously to 
the user using exception. 


Disables a service access point (SAP). This ioctl operation 
does not fully complete the disable SAP processing before 
returning to the user. The DLC_DISABLE_SAP notification 
is returned asynchronously to the user some time later 
using exception. 


Enables a SAP. This ioctl operation does not fully complete 
the enable SAP processing before returning to the user. 
The DLC_ENABLE_SAP notification is returned 
asynchronously to the user some time later using exception. 


Enters local busy mode on an LS. 
Enters short hold mode on an LS. 


Exits local busy mode on an LS. 


DLC_EXIT_SHOLD 
DLC_GET_EXCEP 


DLC_HALT_LS 


DLC_QUERY_LS 
DLC_QUERY_SAP 
DLC_START_LS 


DLC_TEST 


DLC_TRACE 
IOCINFO 
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Exits short hold mode on an LS. 


Returns asynchronous exception notifications to the 
application user. 


Note: This ioctl command operation is not used by the 
kernel user since all exception conditions are 
passed to the kernel user via their exeception 
handler routine. 


Halts an LS. This ioctl operation does not complete 
processing before returning to the user. Notification of the 
ioctl operation, DLC_HALT_LS, is returned asynchronously 
to the user using exception. 


Queries an LS. 
Queries a SAP. 


Starts an LS. This ioctl operation does not complete 
processing before returning to the user. Notification of the 
ioctl operation, DLC_START_LS, is returned 
asynchronously to the user using exception. 


Tests LS connectivity. This ioctl operation does not 
complete processing before returning to the user. 
Notification of the ioctl operation, DLC_TEST completion, 
is returned asynchronously to the user using exception. 


Traces LS activity. 


Returns a structure that describes the device. Refer to the 
description of the sys/devinfo.h file in A/X Version 3 
Application Programming Interface, File Formats. The first 
byte is set to an ioctype of DD_DLC. The subtype and 
data are defined by the individual DLC devices. 


These ioctl operations for DLC are part of the device manager Data Link Control in BOS 


Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 


you decide to use. 


Related Information 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 


Concepts. 
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ioct! Subroutine Operations Parameter Blocks for DLC 
Each command operation has a specific parameter block associated with the command that 
is pointed to by the arg pointer. Some parameters are sent to GDLC and some are returned. 


The ioctl command operations for DLC are as follows: 


e DLC_ENABLE_SAP ioctl Operation for DLC 

e DLC_DISABLE_SAP ioctl Operation for DLC 
e DLC_START_LS ioctl Operation for DLC 

e DLC_HALT_LS ioctl Operation for DLC 

e DLC_TRACE ioctl Operation for DLC 

e DLC_CONTACT ioctl Operation for DLC 

e DLC_TEST ioctl Operation for DLC 
DLC_ALTER ioctl Operation for DLC 
DLC_QUERY_SAP ioctl Operation for DLC 
DLC_QUERY_LS ioctl Operation for DLC 
DLC_ENTER_LBUSY ioctl Operation for DLC 
DLC_EXIT_LBUSY ioctl Operation for DLC 

e DLC_ENTER_SHOLD ioctl Operation for DLC 
e DLC_EXIT_SHOLD ioctl Operation for DLC 

e DLC_GET_EXCEP ioctl Operation for DLC 

e DLC_ADD_GRP ioctl Operation for DLC 

e IOCINFO ioctl Operation for DLC. 


DLC_ENABLE SAP ioctl Operation for DLC 
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The following parameter enables a service access point (SAP). 


#define DLC_MAX NAME 20 /* maximum size of the address/name sd 
#define DLC_MAX GSAPS 7 /* maximum number of group sap */ 
#define DLC_MAX ADDR 8 /* maximum byte length of an address */ 
struct dlc_esap_arg 
{ 
ulong_t gdlc_sap_corr; /* GDLC SAP correlator */ 
/* RETURNED st 5 
ulong_t user_sap_ corr; /* User's SAP correlator */ 
ulong_t len_func_addr_mask; /* length of the field = */ 
/* below it *7 
uchar_t func_addr_mask[DLC_MAX ADDR];/* Mask of the valid at 
/* functional address */ 
ulong_t len_grp_ addr; /* length of the field */ 
/* below it ay 
uchar_t grp_addr[DLC_MAX ADDR]; /* Address of group packet */ 
/* to be received ay, 
ulong_t max_ls; /* Max number of link tg 
/* stations per SAP */ 
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ulong t flags; /* Enable SAP flags */ 
ulong_t len_laddr_name; /* Length of the local */ 

/* name/address */ 
u_char_t laddr_name[DLC_MAX NAME]; /* The local address/name */ 
u_char_t num_grp_saps; /* Number of group SAPs */ 
u_char_t grp_sap[DLC_MAX _GSAPS]; /* Group SAPs the SAP will */ 
/* rsp to */ 
u_char_t res1[3]; /* reserved */ 
u_char_t local_sap; /* ID of local SAP se 
}; 


gdic_sap_corr GDLC SAP correlator: The GDLC’s service access point (SAP) identifier 
that is returned to the user. This correlator must accompany all subsequent 
commands associated with this service access point. 


user_sap_corr User SAP correlator: The user's SAP identifier to be returned by GDLC on 
all SAP results. It allows routing of the SAP-specific results when multiple 
SAPs have been opened by a single user. 


len_func_addr_mask 
Length of functional address mask: Specifies the byte length of the following 
functional address mask. This field must be set to 0 (zero) if no functional 
address is required. Length values of 0 through 8 are supported. 


func_addr_mask 
Functional address mask: The functional address mask to be ORed with the 
functional address on the adapter. This address mask allows packets that 
are destined for specified functions to be received by the local adapter. See 
the individual DLC interface documentation to determine the format and 
length of this field. 


Note: GDLC does not distinguish whether a received packet was accepted 
by the adapter due to a pre-set network, group, or functional 
address. lf the SAP address matches and the packet is otherwise 
valid (no protocol errors, for instance), the received packet is passed 
to the user. 


len_grp_addr Length of group address: Specifies the byte length of the following group 
address. This field must be set to 0 if no group address is required. Length 
values of 0 through 8 are supported. 


grp_addr Group address: The group address value to be written to the adapter. It 
-allows packets that are destined for a specific group to be received by the 
local adapter. 


Note: Most adapters allow only one group address to be active at a time. If 
this field is nonzero and the adapter rejects the group address 
because it is already in use, the enable SAP call fails with an 
appropriate error code. 
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max_lIs Maximum link stations (LS): Specifies the maximum number of LSs allowed 
to operate concurrently on a particular SAP. This field can be set to a value 
from 1 through 255 inclusive. 


flags Common SAP flags: The following flags are supported: 
#define DLC_ESAP_NTWK 0x40000000 /* teleprocessing network */ 
/* type (LEASED) * / 
#define DLC_ESAP_LINK 0x20000000 /* teleprocessing link —R/ 
/* type (multi) * / 
#define DLC_ESAP_PHYC 0x10000000 /* physical network call */ 
#define DLC_ESAP_ANSW 0x08000000 /* teleprocessing auto */ 
/* call/answer * / 
#define DLC_ESAP_ADDR 0x04000000 /* local address/name */ 
/* indicator (ADDR) * / 
DLC_ESAP_NTWK Teleprocessing network type: 
0 = Switched (default) 
1 = Leased. 
DLC_ESAP_LINK Teleprocessing link type: 
0 = Point to point (default) 
1 = Multipoint. 
DLC_ESAP_PHYC Physica! network call (teleprocessing): 


0 = Listen for incoming call. 
1 = Initiate call. 


DLC_ESAP_ADDR Local address or name indicator: 


0 = Local name specified (default) 

1 = Local address specified. 

Specifies whether the local address or name field 
contains an address or a name. 


DLC_ESAP_ANSW Teleprocessing autocall or autoanswer: 


0 = Manual call and answer (default) 
1 = Automatic call and answer. 
len_laddr_name 


Length of local address or name: Specifies the byte length of the following 
local address or name. Length values of 1 through 20 are supported. 


laddr_name Local address or name: Contains the unique network name or address of 
the user’s local SAP as indicated by the DLC_ESAP_ADDR flag. 


num_grp_sapsNumber of group SAPs: Specifies the number of group SAPs the user’s 
local SAP responds to. If no group SAPs are needed, this field must contain 
a 0. Up to seven group SAPs can be specified. 


grp_sap Group SAP array: Contains the specific group SAP values that the user’s 
local SAP responds to (maximum of seven). 
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local_sap Local SAP address: Specifies the local SAP address being opened. Receive 
packets with this LSAP value indicated in the destination SAP field are 
routed to the LSs opened under this particular SAP. 


Protocol Specific Data Area 


Optional: Allows parameters to be defined by the specific GDLC device 
manager, such as X.21 call-progress signals or smartmodem 
call-establishment data. This data area must directly follow (or append to) 
the end of the dic_esap_arg structure. 


Implementation Specifics 
This DLC_ENABLE_SAP ioctl operation for DLC is part of the device manager Data Link 
Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
Parameter Blocks by ioctl Operation for DLC on page . 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


DLC_DISABLE SAP ioctl Operation for DLC 


The following parameter disables a service access point (SAP). 


struct dlc _corr_arg 


ulong t gdlc_sap corr; /* GDLC SAP correlator , ke 
ulong _t gdlc_ls_ corr; /* << not used for disabling a SAP >> */ 
}; 
gdic_sap_corr GDLC SAP correlator: Indicates the GDLC SAP identifier to be 
disabled. 


Implementation Specifics 
This DLC_DISABLE_SAP ioctl operation for DLC is part of the device manager Data Link 
Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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DLC_START_LS ioctl Operation for DLC 


The following parameter starts a link station (LS) on a particular SAP as caller or listener. 
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#define DLC_MAX_ DIAG 16 /* the maximum string of chars */ 


/* 


struct dlc_sls_arg 


in the diag name * 


{ 
ulong t-gdle ls corr; /* GDLC User link station */ 
/* correlator */ 
u_char_t ls _diag[DLC_MAX DIAG]; /* the char name of the ls */ 
ulong_t gdlc_sap_corr; _  /* GDLC SAP correlator */ 
ulong_t user_1ls_ corr; /* User’s SAP correlator */ 
ulong t flags; /* Start Link Station flags */ 
ulong_t trace_chan; /* Trace Channel */ 
/* (re of trestart) * / 
ulong_t len_raddr_name; /* Length of the remote */ 
/* name/addr */ 


u_char_t raddr_name[DLC_MAX NAME]; 
ulong_t maxif; 


ulong_t rev_wind; 
ulong_t xmit_wind; 


u_char_t rsap; 
u_char_t rsap_low; 


u_char_t rsap_high; 


u_char_t resl; 
ulong_t max_repoll; 
ulong_t repoll time; 
ulong_t ack_time; 


/* The Remote addr/name */ 
/* Maximum number of byte*/ 


/* in an I—field */ 
/* Maximum size of the */ 
/* receive window x / 
/* Maximum size of the */ 
/* transmit window . * / 
/* Remote SAP value * / 
/* Remote SAP low range */ 
/* value * / 
/* Remote SAP high range */ 
/* value * / 
/* Reserved */ 


/* Maximum Repoll count */ 
/* Repoll timeout value */ 
/* Time to delay trans of*/ 


/* an ack * / 
ulong_t inact_time; /* Time before inactivity*/ 
/* times out * / 
ulong_t force time; /* Time before a forced */ 
/* disconnect * / 
}; 
gdic_Is_corr GDLC LS correlator: The GDLC LS identifier returned to the user as 
soon as resources are determined to be available. This correlator must 
accompany all commands associated with this LS. 
Is_ diag LS diagnostic tag: Any ASCII 1 to 16-character name to be written to 


GDLC trace, error log, and status entries for LS identification. (The 
end-of-name delimiter is the AIX null character). 


gdic_sap_corr GDLC SAP correlator: The correlator returned by GDLC when the SAP 
is enabled by the user. This correlator identifies the user’s service 
access point to the GDLC protocol process. 
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flags 


#define 
#define 


#define 
#define 


#define 
#define 
#define 
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all results and data. It allows routing of the station-specific results 
when multiple logical links have been started by a single user. 


Common LS flags: The following flags are supported: 


DLC_TRCO 
DLC_TRCL 


DLC_SLS STAT 
DLC_SLS_NEGO 


DLC_SLS_HOLD 
DLC_SLS_LSVC 
DLC_SLS ADDR 


DLC_TRCO 


DLC_TRCL 


DLC _SLS STAT 


DLC_SLS NEGO 


DLC_SLS HOLD 


DLC_SLS_LSVC 


0x80000000 
0x40000000 


0x20000000 


0x10000000 


0x08000000 
0x04000000 
0x02000000 


/* Trace Control On 

/* Trace Control Long 

/* (full packet) 

/* Station type for SDLC 
/* (primary) 


User LS correlator: The user’s LS identifier to be returned by GDLC on 


*/ 
*/ 
ef 
*/ 
ey 


/*Negotiate Station Type for*/ 


/* SDLC 
/* Hold link on inactivity 
/* Link Station Virtual Call 
/* Address Indicator 
/* (not discovery) 


Trace control on: 


0 = Disable !ink trace. 


1 = Enable link trace. 


Trace control long: 


0 = Link trace entries are short (80 bytes). 


1 = Link trace entries are long (full packet). 


Station type for SDLC: 


0 = Secondary (default) 


1 = Primary. 


Negotiate station type for SDLC: 


0 = No (default) 


1 = Yes. 


Hold link on inactivity: 


0 = No (default), terminate the LS. 


1 = Yes, hold it active. 


LS virtual call: 


0 = Listen for incoming call. 


1 = Initiate call. 


od 
arf 
=f 
mf. 
ey 
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trace_chan 


DLC_SLS ADDR Address indicator: 
0 = Remote is identified by name (discovery). 


1 = Remote is identified by address (resolve, 
SDLC). 


Trace channel: Specifies the channel number obtained from the trestart 
subroutine. This field is valid only if the DLC_TRCO indicator is set active. 


len_raddr_name 


raddr_name 


maxif 


rcv_wind 


xmit_wind 


rsap 


rsap_low 


rsap_high 


max_repoll 


Length of remote’s address or name: Specifies the byte length of the remote 
address or name. This field must be set to 0 (zero) if no remote address or 
name is required to start the LS. Length values of 0 through 20 are 
supported. 


Remote’s address or name: Contains the unique network address of the 
remote node if the DLC_SLS_ADDR indicator is set active. Contains the 
unique network name of the remote node if the DLC_SLS_ADDR indicator 
is reset. Addresses are entered in hexadecimal notation, and names are 
entered in character notation. This field is only valid if the previous length 
field is nonzero. 


Maximum I-field length: Specifies the maximum number of I-field bytes that 
can be in one packet. This value is reduced by GDLC if the device handler’s 
buffer sizes are too small to hold the maximum I-field specified here. The 
resultant size is returned from GDLC when the link station has been started. 


Receive window: The receive window specifies the maximum number of 
sequentially numbered receive I-frames the local station can accept prior to 
sending an acknowledgment. 


Transmit window: The transmit window specifies the maximum number of 


sequentially numbered transmitted |-frames that can be outstanding at any 
time. 


Remote SAP: Specifies the remote service access point address being 
called. This field is valid only if the DLC_SLS_LSVC indicator or the 
DLC_SLS_ ADDR indicator is set active. 


RSAP low range: Specifies the lowest value in the range of remote SAP 
address values that the local SAP responds to when listening for a 
remote-initiated attachment. This value cannot be the Null SAP (0x00) or 
the Discovery SAP (OxFC), and must have the low-order bit set to 0 
(B'nnnnnnn0d’) to indicate an individual address. 


RSAP high range: Specifies the highest value in the range of remote SAP 
address values that the local SAP responds to, when listening for a 
remote-initiated attachment. This value cannot be the Null SAP (0x00) or 
the Discovery SAP (OxFC), and must have the low-order bit set to 0 
(B‘nnnnnnn0’) to indicate an individual address. 


Maximum repoll count: Specifies the maximum number of retries for an 
unacknowledged command frame, or in the case of an I-frame time out, the 
number of times the nonresponding remote link station is polled with a 
supervisory command frame. 
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repoll_ time Repoll time-out value: Contains the time-out value (in increments defined by 
the specific GDLC) used to specify the amount of time allowed prior to 
retransmitting an unacknowledged command frame. 


ack_time Acknowledgment time-out: Contains the time-out value (in increments 
defined by the specific GDLC) used to specify the amount of time to delay 
the transmission of an acknowledgment for a received I-frame. 


inact_time Inactivity time-out value: Contains the time-out value (in increments of 1 


second) used to specify the maximum amount of time allowed before 
receive inactivity returns an error. 


force_time Force halt time-out value: Contains the time-out value (in increments of 1 
second) specifying the period to wait for a normal disconnection. Once the 
time-out occurs, the disconnection is forced and the link station halted. 


Protocol Specific Data Area 
Optional: Allows parameters to be defined by a specific GDLC device 
manager, such as token-ring dynamic window increment or SDLC primary 
slow poll. This data area must directly follow (or append to) the end of the 
dic_sls_arg structure. 


Implementation Specifics 
This DLC_START_LS ioctl operation for DLC is part of the device manager Data Link 
Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


DLC_HALT LS ioctl Operation for DLC 


The following parameter halts a link station (LS). 


struct. ‘dic corr arg 


{ 
ulong_t gdlc_sap corr; /* GDLC SAP correlator * / 
ulong_t gdlc_ls_corr; /* GDLC link station correlator */ 
}3 


gdic_sap_corr GDLC SAP correlator: The GDLC SAP identifier of the target LS. 


gdic_Is_corr GDLC LS correlator: The GDLC LS identifier to be halted. 


implementation Specifics 
This DLC_HALT_LS ioctl operation for DLC is part of the device manager Data Link Control 
in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 
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Related Information 
: Generic Data Link Contro! (GDLC) Environment Overview in Communications Programming 
Concepts. 


DLC_TRACE ioctl Operation for DLC 


The following parameter traces a link stations (LS) activity for short or long activities. 


struct dic_trace arg 


{ 
ulong_t gdlc_sap_ corr; /* GDLC SAP correlator */ 
ulong t gdic is. corr; /* GDLC link station correlator */ 
ulong_t trace_chan; /* Trace Channel (re of trcstart) */ 
ulong_t flags; /* Trace Flags */ 
}; 


gdic_sap_corr GDLC SAP correlator: The correlator returned by GDLC when the SAP 
was enabled by the user. This correlator identifies the user’s service 
access point to the GDLC protocol process. 


gdic_Is_corr GDLC LS correlator: The correlator returned by GDLC when the LS 
was Started by the user. This correlator identifies the user’s LS to the 
GDLC protocol process. 


trace_chan Trace channel: Specifies the channel number obtained from the 
trestart subroutine. This field is only valid if the DLC_TRCO indicator 
is set active. 

flags Trace flags: The following flags are supported: 

#define DLC_TRCO 0x80000000 /* Trace Control On * f/f 

#define DLC_TRCL 0x40000000 /* Trace Control Long ay 

/* (full packet) * / 
DLC _TRCO Trace control on: 


0 = Disable link trace. 
1 = Enable link trace. 
DLC_TRCL Trace control long: 
0 = Link trace entries are short (80 bytes). 


1 = Link trace entries are long (full packet). 


implementation Specifics 
This DLC_TRACE ioctl operation for DLC is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. . 
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Related Information 
Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


DLC CONTACT iocti Operation for DLC 


The following parameter contacts a remote station for a particular local link station (LS). 


struct dlc_corr_arg 


{ 
ulong_t gdlc_sap corr; /* GDLC SAP correlator i 6 
ulong t gdlc_ls_ corr; /* GDLC link station correlator */ 
}; 


gdic_sap_corr GDLC SAP correlator: The GDLC SAP identifier of the target LS. 


gdic_lts_ corr GDLC LS correlator: The GDLC LS identifier to be contacted. 


Implementation Specifics 
This DLC_CONTACT ioctl operation for DLC is part of the device manager Data Link Control 
in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


DLC_TEST ioctl Operation for DLC 


The following parameter tests the link to a remote for a particular local link station (LS). 


struct dlc corr _arg 


{ 
ulong_t gdlc_sap_corr; /* GDLC SAP correlator Ay 
ulong_t gdlc_ls_ corr; /* GDLC link station correlator */ 
}; 


gdic_sap_corr GDLC SAP correlator: The GDLC SAP identifier of the target LS. 


gdic_ls_corr GDLC LS correlator: The GDLC LS identifier to be tested. 


Implementation Specifics 
This DLC_TEST ioctl operation for DLC is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 
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Related Information 
Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


DLC_ ALTER ioctl Operation for DLC 


The following parameter alters a link station’s (LS) configuration parameters. 
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#define DLC_MAX ROUT 


struct dlc_alter_arg 





20 /* Maximum Size of Routing Info 


{ 

ulong_t gdlc_sap_corr; /* GDLC SAP correlator 
ulong_t gdlc_ls_corr; /* GDLC link station correlator 
ulong_t flags; /* Alter Flags 

ulong_t repoll time; /* New Repoll Timeout 
ulong_t ack_time; /* New Acknowledge Timeout 
ulong_t inact_time; /* New Inactivity Timeout 
ulong_t force_time; /* New Force Timeout 
ulong_t maxif; /* New Maximum I-—Frame Size 
ulong_t xmit_wind; /* New Transmit Value 
ulong_t max_repoll; /* New Max Repoll Value 
ulong_t routing_len; /* Routing Length 


u_char_t routing[DLC_MAX ROUT]; /* New Routing Data 
ulong_t result_flags; 


ie 


gdic_sap_corr 


gdic_Is_corr 


flags 


#define 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


#define 


#define 


#define 


/* Returned flags 


GDLC SAP correlator: The GDLC SAP identifier of the target LS. 


GDLC LS correlator: The GDLC LS identifier to be altered. 


Alter flags: The following flags are supported: 


DLC_ALT RTO 
DLC_ALT AKT 
DLC_ALT ITO 
DLC_ALT FHT 
DLC_ALT MIF 
DLC_ALT XWIN 
DLC_ALT MXR 
DLC_ALT RTE 
DLC_ALT SM1 


DLC_ ALT SM2 
DLC ALT 171 


DIC ALT 172 
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0x80000000 
0x40000000 
0x20000000 
0x10000000 
0x08000000 
0x04000000 
0x02000000 
0x01000000 
0x00800000 


0x00400000 


0x00200000 


0x00100000 


*/ 


* / 
*/ 
*/ 
*/ 
* / 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
+] 


/* Alter Repoll Timeout */ 
/* Alter Acknowledge Timeout */ 
/* Alter Inactivity Timeout */ 
/* Alter Force Halt Timeout */ 
/* Alter Maximum I—Frame Size*/ 
/* Alter Tranxmit Window Size*/ 
/* Alter Maximum Repoll Count*/ 
/* Alter Routing */ 
/* Alter Mode (SDLC) bit 1 * / 
/* (Primary) */ 
/* Alter Mode (SDLC) bit 2 */ 
/* (Secondary) */ 
/* Alter Inactivity bit 1 * / 
/* (Notify) */ 
/* Alter Inactivity bit 2 * / 
/* (Halt) * / 
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DLC_ALT_RTO Alter repoll time out: 
0 = Do not alter repoll time out. 
1 = Alter configuration with value specified. 


Alters the length of time the LS waits for a response before 
repolling the remote station. When specified, the repol! time 
out value specified in the LS’s configuration is overridden by 
the value supplied in the repoll time-out field of the Alter 
command. This new value remains in effect until another 
value is specified or the LS is halted. 


DLC_ALT_AKT Alter acknowledgment time out: 
0 = Do not alter the acknowledgment time out. 
1 = Alter configuration with value specified. 


Alters the length of time the LS delays the transmission of 
an acknowledgment for a received |-frame. When specified, 
the acknowledgment time out value specified in the LS’s 
configuration is overridden by the value supplied in the 
acknowledgment time-out field of the Alter command. This 
new value remains in effect until another value is specified 
or the LS is halted. 


DLC_ALT_!ITO Alter inactivity time out: 
0 = Do not alter inactivity time out. 


1 = Alter configuration with value specified. 


Alters the maximum length of time allowed without receive 
link activity from the remote station. When specified, the 
inactivity time-out value specified in the LS’s configuration is 
overridden by the value supplied in the inactivity time-out 
field of the Alter command. This new value remains in 
effect until another value is specified or the LS is halted. 


DLC_ALT_FHT Alter force halt time out: 
0 = Do not alter force halt time out. 
1 = Alter configuration with value specified. 


Alters the period to wait for a normal disconnection before 
forcing the halt LS to occur. When specified, the force halt 
time-out value specified in the LS’s configuration is 
overridden by the value supplied in the force halt time-out 
field of the Alter command. This new value remains in 
effect until another value is specified or the LS is halted. 


DLC_ALT_MIF Maximum I-field length: 
0 = Do not alter maximum I-field length. 


1 = Alter configuration with value specified. 
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DLC_ALT_RTE 


DLC_ALT_SM1 
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Sets the value for the maximum length of transmit or 
receive data in one I-field. If received data exceeds this 
length, a buffer overflow indication set by GDLC in the 
receive extension. When specified, the maximum I-field 
length value specified in the LS’s configuration is overridden 
by the value supplied in the maximum I-field length 
specified in the Alter command. This new value remains in 
effect until another value is specified or the LS is halted. 


DLC_ALT_XWIN Alter transmit window: 


0 = Do notalter transmit window. 
1 = Alter configuration with value specified. 


Alters the maximum number of information frames that can 
be sent in one transmit burst. When specified, the transmit 
window count value specified in the LS’s configuration is 


- overridden by the value supplied in the transmit window 


field of the Alter command. This new value remains in 
effect until another value is specified or the LS is halted. 


DLC_ALT_MXR Alter maximum repoll: 


0 = Do not alter maximum repoll. 
1 = Alter configuration with value specified 


Alters the maximum number of retries for an acknowledged 
command frame, or in the case of an I-frame time out, the 
number of times the nonresponding remote LS will be 
polled with a supervisory command frame. When specified, 
the maximum repol! count value specified in the LS’s 
configuration is overridden by/the value supplied in the 
maximum repoll count field of the Alter command. This new 
value remains in effect until another value is specified or the 
LS is halted. 


Alter routing: 
0 = Do not alter routing. 
1 = Alter configuration with value specified. 


Alters the route that subsequent transmit packets take when 
transferring data across a local area network bridge. When 
specified, the routing length and routing data values 
specified in the LS’s configuration are overridden by the 
values supplied in the routing fields of the Alter command. 
These new values remain in effect until another route is 
specified or the LS is halted. 


Set SDLC Control mode — primary: 
0 = Do not alter SDLC Control mode. 


1 = Set SDLC Control mode to primary. 


repoll_time 


ack_time 


inact_time 


force_time 


maxif 


xmit_wind 
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Sets the local station to a primary station in NDM, waiting 
for a command from PU services to write an XID or TEST, 
or a command to contact the secondary for NRM data 
phase. This contro! can only be issued if not already in 
NRM, and no XID, TEST, or SNRM is in progress. This flag 
cannot be set if the DLC_ALT_SM2 flag is set. 


DLC_ALT_SM2 Set SDLC Control mode — secondary: 
0 = Do not alter SDLC Control mode. 
1 = Set SDLC Control mode to secondary. 


Sets the local station to a secondary station in NDM, waiting 
for XID, TEST, or SNRM from the primary station. This 
control can only be issued if not already in NRM, and no 
XID, TEST, or SNRM is in progress. This flag cannot be set 
if the DLC_ALT_SMt1 flag is set. 


DLC_ALT_IT1 Set Inactivity Time Out mode — notification only: 
0 = Do notalter Inactivity Time Out mode. 
1 = Set Inactivity Time Out mode to notification only. 


Inactivity does not cause the LS to be halted, but notifies 
the user of inactivity without termination. 


DLC_ALT_IT2 Set Inactivity Time Out mode — automatic halt: 
0 = Do not alter Inactivity Time Out mode. 
1 = Set Inactivity Time Out mode to automatic halt. 


Inactivity causes an automatic halt of the LS with a reason 
code of inactivity. 


Repoll time-out value: Provides a new value to replace the LS’s repoll 
time-out value whenever the DLC_ALT_RTO flag is set. 


Acknowledge time-out value: Provides a new value to replace the LS’s 
acknowledgment time-out value whenever the DLC_ALT_AKT flag is set. 


Inactivity time-out value: Provides a new value to replace the LS’s inactivity 
time-out value whenever the Alter DLC_ALT_ITO flag is set. 


Force halt time-out value: Provides a new value to replace the LS’s force 
halt time-out value whenever the DLC_ALT_FHT flag is set. 


Maximum I-field size value: Provides a new value to replace the LS started 
result value for the maximum I-field size whenever the DLC_ALT_MIF flag 
is set. GDLC does not allow this value to exceed the capacity of receive 
buffer and only increases the internal value to the allowed maximum. 


Transmit window value: Provides a new value to replace the LS’s transmit 
window count value whenever the DLC_ALT_XWIN flag is set. 
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max_repoll Maximum repoll count value: Provides the new value that is to replace the 
LS’s maximum repoll count value whenever the DLC_ALT_MXR flag is set. 

routing len Routing field length value: Provides a new value to replace the LS’s routing 
field length whenever the DLC_ALT_RTE flag is set. 

routing Routing data field value: Provides a new value to replace the LS’s routing 
data whenever the DLC_ALT_RTE flag is set. 

result_flags Returned result indicator flags: The following result indicators may be 
returned at the completion of the alter operation, depending on the 
command: 

#define DLC_MSS_RES 0x00040000 /* Mode Set Secondary * 

#define DLC_MSSF_RES 0x00020000 /* Mode Set Secondary Failed */ 

#define DLC_MSP_RES 0x00010000 /* Mode Set Primary ua 

#define DLC_MSPF_RES 0x00008000 /* Mode Set Primary Failed ae A 


DLC_MSS_RES Mode set secondary: 


This bit set to 1 indicates that the station mode has been 
set to secondary as a result of the user’s issuing an Alter 
(set mode secondary) command. 


DLC_MSSF_RES Mode set secondary failed: 


This bit set to 1 indicates that the station mode has been 
not set to secondary as a result of the user’s issuing an 
Alter (set mode secondary) command. This occurs 
whenever an SDLC LS is already in data phase or an SDLC 
primary command sequence has not yet completed. 


DLC_MSP_RES Mode set primary: 


This bit set to 1 indicates that the station mode has been 
set to primary as a result of the user’s issuing an Alter (set 
mode primary) command. 


DLC_MSPF_RES Mode set primary failed: 


This bit set to 1 indicates that the station mode has not 
been set to primary as a result of the user’s issuing an Alter 
(set mode primary) command. This occurs whenever an 
SDLC LS is already in data phase. 


Protocol Dependent Area 


Optional: Allows additional fields to be provided by a specific protocol type. 
Corresponding flags may be necessary to support additional fields. This 
data area must directly follow (or append to) the end of the dic_alter_arg 
structure. 


Base Operating System Reference 


implementation Specifics 
This DLC_ALTER ioctl operation for DLC is part of the device manager Data Link Control in 
BOS Extensions 2. 


ioctl (op) 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 


Concepts. 


DLC_QUERY_SAP ioctl Operation for DLC 


The following parameter queries statistics of a particular service access point (SAP). 


#define DLC_MAX DIAG 16 /* the max string of chars in the */ 


/* diag 


struct dlic_qsap_arg 


{ 


ulong t 
ulong t 
ulong t 


uchar_t 
ulong t 


‘3 


gdic_sap_corr 


user_sap_corr 


sap_state 


#define DLC_ 


#define DLC_ 
#define DLC | 


dev 


devdd_len 


gdlc_sap corr; 
user _sap_corr; 
sap_state; 


dev[DLC_ MAX DIAG]; 


devdd_len; 


GDLC SAP correlator: The GDLC SAP identifier to be queried. 


name */ 


/* GDLC SAP correlator 
/* user SAP correlator (returned) */ 
/* state of the SAP, returned by */ 
/* the kernel 
/* the returned device handler’s */ 
/* device name 


/* device driver dependent data 


/* byte length 


ey. 


cf 


xf 
*/ 
*/ 


User SAP correlator: The user’s identifier for the SAP, returned for 


routing purposes. 


Current SAP state: Contains the current state of this SAP: 


OPENING 1 ass 
/* 
OPENED 2 ie 
CLOSING 3 /* 
/* 


Device handler dev name: 


the SAP 


process 


the SAP 
the SAP 
process 


or 
of 
or 
or 
of 


link station is in the */ 


opening 


ls has been opened 


*/ 
*/ 


link station is in the */ 


closing 


*/ 


Contains the /dev name of the communications 
I/O device handler being used by this SAP. 


Length of device driver dependent data: Contains the byte length of the 
expected device driver statistics that will be appended to the dic_qsap_arg 


structure. 
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Device Driver Dependent Data 
Optional: Contains the device statistics of the attached device handler. This 
may be the query device statistics (reliability/availability/serviceability log 
area) returned from a DLC_Query_LS, or if supported by the device 
handler, this may be the result of aDLC_Query_ SAP issued to the attached 
device handler. See the individual device handler’s specifications for 
information on the particular fields returned. This data area must directly 
follow (or append to) the end of the dlc_qsap_arg structure. 


Implementation Specifics 
This DLC_QUERY_SAP ioctl operation for DLC is part of the device manager Data Link 
Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


DLC_QUERY LS ioctl Operation for DLC 


The following parameter queries statistics of a particular link station (LS). 


struct dlc_qls_arg 


{. 

ulong_t gdlc_sap_corr; /* GDLC SAP correlator mf 

ulong_t gdlc_ls_corr; /* GDLC 1s correlator air 

ulong_t user_sap_corr; /* user’s SAP correlator 1 
/* — RETURNED *7/ 

ulong_t user_ls_ corr; /* user’s link station * / 


/* corr — RETURNED */ 
u_char_t ls _diag[DLC_MAX DIAG]; /* the char name of the ls */ 


ulong_t ls_state; /* current ls state a 
ulong_t ls_sub_state; /* further clarification sad 
/* of state */ 
struct dlc_ls counters counters; 
ulong_t protodd_len; /* protocol dependent data */ 
/* byte length */ 
}; 
gdic_sap_corr GDLC SAP correlator: The GDLC SAP identifier of the target LS. 
gdic_Is_ corr GDLC LS correlator: The GDLC LS identifier to be queried. 
user_Sap_corr User SAP correlator: The user’s SAP identifier returned for routing 
purposes. 
user_Is_corr User LS correlator: The user’s LS identifier returned for routing 
purposes. 


3—48 Base Operating System Reference 


ioctl (op) 


Is_diag Link station diagnostic tag: Contains the ASCII character string tag 
passed to GDLC at the DLC_START_LS ioctl operation to identify the 
station being queried. For example, SNA Services puts the attachment 
profile name in this field. 


Is_state Current station state: Contains the current state of this LS: 

#define DLC_OPENING 1 /* the SAP or link station is in the */ 
/* process of opening * / 

#define DLC_OPENED 2 /* the SAP or 1s has been opened as 

#define DLC_CLOSING 3 /* the SAP or link station is in the */ 
/* process of closing my. 

#define DLC_INACTIVE 4 /* the link station is in an inactive */ 
/* state at present x / 

Is_sub_state Current station substate: Contains the current substate of this LS. 


Several indicators may be active concurrently. 


#define DLC_CALLING 0x80000000 /* the ls is calling a) 
#define DLC_LISTENING 0x40000000 /* the ls is listening beg 
#define DLC_CONTACTED 0x20000000 /* the ls is contacted into */ 

/* sequenced data mode * / 
#define DLC_LOCAL BUSY 0x10000000 /* the local link station is */ 

/* busy right now */ 
#define DLC_REMOTE BUSY 0x08000000 /* the remote link station = 

/x* is busy right now 47 
counters Link station reliability/availability/serviceability counters: These 14 


reliability/availability/serviceability counters are shown as an example 
only. Each GDLC device manager provides as many of these counters 
as necessary to diagnose specific network problems for its protocol 
type. 


struct dlc_ls_ counters 


{ 


ulong_t test_cmds_sent; /* number of test commands sent */ 
ulong t test_cmds_ fail; /* number of test commands failed */ 
ulong t test_cmds_rec; /* num of test commands received */ 


ulong t data_pkt_sent; /* number of sequenced data */ /* pa 
ckets sent */ 


ulong_t data_pkt_resent; /* number of sequenced data =f 
/* packets resent * / 
ulong_t max_cont_resent; /* maximum number of contiguous ey 
/* resendings * / 
ulong t data_pkt_rec; /* data packets received ay. 
ulong_t inv_pkt_rec; /* num of invalid packets rcvd * / 
ulong_t adp rec err; /* number of data detected ty 
/* receive errors my 
ulong_t adp_send err; /* number of data_detected ei} 
/* transmit errors */ 
ulong _t rec_inact_to; /* number of received inactivity tf 
/* timeouts af 
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ulong_t cmd_polls_sent; /* number of command polls sent */ 
ulong_t cmd_repolls_ sent /* number of command repolls sent */ 
ulong_t cmd_cont_repolls;/* maximum number of continuous */ 
/* repolls sent */ 
}; 
protodd_len Length of protocol dependent data: Contains the byte length of the following 


area. 


Protocol Dependent Data 


Optional: Contains any additional statistics that a particular GDLC device 
manager might provide. See the individual GDLC specifications for 
information on the specific fields returned. This data area must directly 
follow (or append to) the end of the dilc_qls_arg structure. 


Implementation Specifics 


This DLC_QUERY_LS ioctl operation for DLC is part of the device manager Data Link 
Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


DLC _ENTER_LBUSY ioctl Operation for DLC 


The following parameter enters local busy mode on a particular link station (LS). 


struct dlcec_corr_arg 


| 
ulong_t gdlc_sap_ corr; /* GDLC SAP correlator * / 
uliong.-© -gdiels: corr. /* GDLC link station correlator */ 
}; 


gdic_sap_corr GDLC SAP correlator: The GDLC SAP identifier of the target LS. 
gdic_Is_ corr GDLC LS correlator: The GDLC LS identifier to enter local busy mode. 


Implementation Specifics 


This DLC_ENTER_LBUSY ioctl operation for DLC is part of the device manager Data Link 
Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
Parameter Blocks by ioctl Operation for DLC. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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DLC _EXIT_LBUSY ioctl Operation for DLC 


The following parameter exits local busy mode on a particular link station (LS). 


struct dlc_corr_arg 


{ 
ulong_t gdlc_sap_corr; /* GDLC SAP correlator */ 
ulong t gdle-ls corr; /* GDLC link station correlator */ 
}; 


gdic_sap_corr GDLC SAP correlator: The GDLC SAP identifier of the target LS. 
gdic_Is_corr GDLC LS correlator: The GDLC LS identifier to exit local busy mode. 


Implementation Specifics 
This DLC_EXIT_LBUSY ioctl operation for DLC is part of the device manager Data Link 
Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


DLC_ENTER_SHOLD ioctl Operation for DLC 


The following parameter enters short hold mode on a particular link station (LS). 


struct dlc_corr_arg 


{ 
ulong_t gdlc_sap corr; /* GDLC SAP correlator e/ 
ulong_t gdlc_ls corr; /* GDLC link station correlator */ 
}; 


gdic_sap_ corr GDLC SAP correlator: The GDLC SAP identifier of the target LS. 
gdic_Is_corr GDLC LS correlator: The GDLC LS identifier to enter short hold mode. 


Implementation Specifics 


This DLC_ENTER_SHOLD ioctl operation for DLC is part of the device manager Data Link 
Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
Parameter Blocks by ioctl Operation for DLC. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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DLC_EXIT_SHOLD ioctl Operation for DLC 


The following parameter exits short hold mode on a particular link station (LS). 


Struct: dic corr arg 


ulong_t gdlc_sap corr; 
ulong_ t gdlc_ls_corr; 


}; 


gdic_sap_corr 


gdic_Is_corr 


Implementation Specifics 
This DLC_EXIT_SHOLD ioctl operation for DLC is part of the device manager Data Link 


Control in BOS Extensions 2. 


/* GDLC SAP correlator 
/* GDLC link station correlator 


GDLC SAP correlator: The GDLC SAP identifier of the target LS. 


*/ 
*/ 


GDLC LS correlator: The GDLC LS identifier to exit short hold mode. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 


you decide to use. 


Related Information 
Generic Data Link Control (GDLC) Environment Overview in Communications Programming 


Concepts. 


DLC_GET_EXCEP ioctl Operation for DLC 


The following parameter returns asynchronous exception notifications to the application 
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user. 


struct dlc_getx_arg 


{ 


ulong_t user_sap_corr; /* user SAP corr — RETURNED */ 

ulong_t user_1ls_corr; /* user ls corr — RETURNED */ 

ulong_t result _ind; /* the flags identifying the */ 
/* type of excep * / 

int result_code; /* the manner of excep +f 

u_char_t result_ext[DLC_MAX EXT]; /* excep specific ext */ 

}; 

user_Sap_corr User service access point (SAP) 


user_Is_corr 


result_ind 


#define 
#define 
#define 
#define 
#define 
#define 
#define 


#define 
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for this exception. 


exception. 


Result indicators: 


DLC_TEST RES 
DLC_SAPE_RES 
DLC_SAPD_ RES 
DLC_STAS RES 
DLC_STAH_ RES 
DLC_DIAL RES 
DLC_IWOT_RES 


DLC_IEND RES 


0x08000000 
0x04000000 
0x02000000 
0x01000000 
0x00800000 
0x00400000 
0x00200000 


0x00100000 


User link station (LS) correlator: The user’s LS identifier for this 


/* a test cmd completion 
/* an enable SAP completion 
/* a disable SAP completion 
/* a start 1s completion 
/* a halt 1s completion 
/* manually dial the phone now 
/* inactivity without 
/* termination 
/* the inactivity has ended 


correlator: The user’s SAP identifier 


zy, 
*/ 
x}. 
*/ 
*/ 
* 
*/ 
*/ 
*/ 


ioctl (op) 


#define DLC CONT RES 0x00080000 /* the station is now a7 
/* contacted ed 
#define DLC_RADD RES 0x00004000 /* the remote addr has changed */ 
#define DLC MAX EXT 48 /* max size of the result ay 
/* extension field a 


DLC_TEST_RES 


DLC_SAPE_RES 


DLC_SAPD_RES 


DLC_STAS_RES 


DLC_STAH RES 


DLC_DIAL_RES 


DLC_IWOT_RES 


DLC_IEND_RES 


Test complete: A nonextended result. Set to 1, 
this bit indicates that the link test has completed 
as indicated in the result code. 


SAP enabled: An extended result. Set to 1, this 
bit indicates that the SAP is active and ready for 
LSs to be started. See DLC_SAPE_RES 
operation for the format of the extension area. 


SAP Disabled: A nonextended result. Set to 1, 
this bit indicates that the SAP has been 
terminated as indicated in the result code. 


Link station started: An extended result. Set to 1, 
this bit indicates that the link station is connected 
to the remote station in asynchronous or normal 
disconnected mode. GDLC is waiting for link 
receive data from the device driver, or additional 
commands from the user such as the 
DLC_CONTACT ioctl operation. See 
DLC_STAS_RES operation for the format of the 
extension area. 


Link station halted: A nonextended result. Set to 
1, this bit indicates that the LS has terminated 
due to a DLC_HALT_LS ioctl operation from the 
user, a remote discontact, or an error condition 
indicated in the result code. 


Dial the phone: A nonextended result. Set to 1, 
this bit indicates that the user may now manually 
dial an outgoing call to the remote station. 


Inactivity without termination: A nonextended 
result. Set to 1, this bit indicates that the LS 
protocol activity from the remote station has 
terminated for the length of time specified in the 
configuration (receive inactivity time out). The 
local station remains active and notifies the user 
if the remote station begins to respond. 
Additional notifications of inactivity without 
termination are suppressed until the inactivity 
condition clears up. 


Inactivity ended: A nonextended result. Set to 1, 
this bit indicates that the LS protocol activity from 
the remote station has restarted after a condition 
of inactivity without termination. 
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DLC_CONT_RES 


DLC_RADD_RES 


Contacted: A nonextended result. Set to 1, this 
bit indicates that GDLC has either received a Set 
Mode, or has received a positive response to a 
Set Mode initiated by the local LS. GDLC is now 
able to send and receive normal sequenced data 
on this LS. 


Remote address/name change: An extended 
result. Set to 1, this bit indicates that the remote 
LS address (or name) has been changed from 
the previous value. This can occur on SDLC links 
when negotiating a point to point connection, for 
example. See the DLC_RADD_RES operation 


for the format of the extension area. 


Result code: The following values specify the result codes for GDLC. 


Negative return codes that are even indicate that the error condition can be 
remedied by restarting the LS returning the error. Return codes that are odd 


indicate that the error is catastrophic, and, at the minimum, the SAP must 


be restarted. Additional error data may be obtained from the GDLC error log 


result_code 

and link trace entries. 
#define DLC_SUCCESS 0 
#define DLC_PROT ERR —906 
#define DLC_BAD DATA —908 
#define DLC_NO_RBUF —910 
#define DLC_RDISC —912 
#define DLC_DISC_TO —914 
#define DLC_INACT TO —916 
#define DLC_MSESS_RE —918 
#define DLC_NO_ FIND —920 
#define DLC_INV_RNAME —922 
#define DLC_SESS LIM —924 
#define DLC_LST_IN_PRGS —926 
#define DLC_LS NT_COND —928 
#define DLC_LS_ ROUT —930 
#define DLC_REMOTE_BUSY —932 
#define DLC_REMOTE_ CONN —936 
#define DLC_NAME_IN_USE —901 
#define DLC_LINV_LNAME -903 
#define DLC_SAP_NT_COND —905 
#define DLC _SAP_ ROUT —907 
#define DLC_USR_INTRF -—909 
#define DLC_ERR_CODE —911 
#define DLC_SYS_ERR —913 
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/* the result indicated was */ 
/* successful */ 
/* protocol error */ 
/* a bad data compare on a TEST */ 
/* no remote buffering on test */ 
/* remote initiated discontact * / 
/* discontact abort timeout */ 
/* inactivity timeout * / 
/* mid session reset */ 
/* cannot find the remote name */ 
/x invalid remote name * / 
/* session limit exceeded */ 
/* listen already in progress * / 
/* 1s unusual network condition */ 
/* link station resource outage * / 
/* remote station found, but busy */ 
/* specified remote is already */ 
/* connected */ 

/* local name already in use */ 
/* invalid local name */ 
/* SAP network unusual network */ 
/* condition * / 
/* SAP resource outage */ 
/* user interface error */ 
/* error in the code has been */ 
/* detected * / 
/* */ 


system error 
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result_ext Result extension: Several results carry extension areas to provide additional 
information about them. The user must provide a full sized area for each 
result requested since there is no way to tell if the next result is extended or 
nonextended. The extended result areas are described by type below. 


DLC_SAPE_RES — SAP Enabled Result Extension 


The following parameter’s service access point (SAP) enables a result extension. 


struct dic_sape_res 


{ 

ulong t max_net_send; /* maximum write network */ 
/* data length * / 

ulong t lport_addr_len; /* local port network * / 
/* address length */ 

u_char_t lport_addr[DLC_MAX ADDR]; /* the local port Ws 
/* address ge 

}i 


max_net_send Maximum write network data length: The maximum number of bytes that the 
user can write for each packet when writing network data. This is generally 
based on a communications mbuf/mbuf’s page cluster size, but is not 
necessarily limited to a single mbuf/mbuf’s since mbuf/mbuf’s can be linked. 


lport_addr_len Local port net address length: Contains the byte length of the local port 
network address. 


Iport_addr Local port network address: Contains the hexadecimal value of the local 
port network address. 


DLC_STAS_RES — Link Station Started Result Extension 


The following parameter starts a link station’s (LS) result extension. 


struct dlc _stas_res 


{ 
ulong_t maxif; /* max size of the data sent */ 
/* on a write */ 
ulong_t rport_addr_ len; /* remote port network */ 
/* address length * / 
u_char_t rport_addr[DLC_MAX ADDR]; /* remote port address <7 
ulong_t rname_len; /* remote network name length */ 
u_char_t rname[DLC_MAX NAME]; /* remote network name */ 
uchar_t res[3]; /* reserved * / 
uchar_t rsap; /* remote SAP us 
ulong_t max_data_off; /* the maximum data offsets a7 
/* for sends */ 

}; 

maxif Maximum I-field size: Contains the maximum byte size allowable for user 


data. This value is derived from the value supplied by the user at start link 
station (DLC_START_LS) and the actual number of bytes that can be 
handled by the GDLC and device handler on a single transmit or receive. 
Generally this value is something less than the size of a communications 
mbuf page cluster. However, some communications devices may be able to 
link page clusters together, so the maximum I-field receivable may be even 
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greater than the length of a single mbuf. The returned value will never 
exceed the value supplied by the user, but may be smaller if buffering is not 
large enough to hold the specified value. 


rport_addr_len Remote port network address length: Contains the byte length of the remote 
port network address. 


rport_addr Remote port network address: Contains the hexadecimal value of the 
remote port network address. 


rname_len Remote network name length: Contains the byte length of the remote port 
network name. This is returned only when name discovery procedures are 
used to locate the remote station. Otherwise this field is set to zero. Network 
names can be 1 to 20 characters in length. 


rname Remote network name: Contains the name being used by the remote SAP. 
This field is valid only if name-discovery procedures were used to locate the 
remote station. 


rsap Remote SAP: Contains the hexadecimal value of the remote SAP address. 


max_data_off Write data offset: Contains the data offset in bytes of a communications 
mbuf where transmit data must minimally begin. This allows ample room for 
the DLC and MAC headers to be inserted if needed. Some DLC’s may be 
able to prepend additional mbufs for their headers, and will set this field to 
zero. 


This field is only valid for kernel users that pass in a communications mbuf 
on write operations. 


Note: In order to align the data moves to a particular byte boundary, the 
kernel user may wish to choose a value larger than the minimum 
value returned 


DLC_STAH_RES — Link Station Halted Result Extension 


The following parameter halts the link station (LS) result extension. 


struct dlc_stah_res 


{ 
ulong conf_ls_corr; /* conflicting link station corr */ 


} 


This extension is valid only if the result code value indicates —936 (specified remote is 
already connected). 


conf_ls_corr Conflicting link station correlator: Contains the user’s link station identifier 
that already has the specified remote station attached. 


DLC_RADD_RES — Remote Address/Name Change Result Extension 
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The following parameter changes the remote address or name of the result extension. 


struct dlc_radd_res 


{ 
ulong rname_len; /* remote network name/addr length */ 
u_char rname[DLC_MAX NAME]; /* remote network name/addr ued 
}; 
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rname_len Remote network address or name length: Contains the byte length of the 
updated remote service access point (SAP)’s network address or name. 


rname Remote network address or name: Contains the updated address or name 
being used by the remote SAP. 


Implementation Specifics 
This DLC_GET_EXCEP ioctl operation for DLC is part of the device manager Data Link 
Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


DLC _ADD_ GRP loctl Operation for DLC 


The following parameter adds a group or multicast receive address. 


struct dlc_add_grp 


{ 
ulong_t gdlc_sap_corr; /* GDLC SAP correlator */ 
ulong_t grp_addr_len; /* group address length */ 
uchar_t grp_addr[DLC_ MAX ADDR]; /* grp addr to be added */ 
}; 


gdic_sap_corr GDLC SAP Correlator: This is GDLC’s SAP identifier being requested 
to add a group or multicast address to a port. 


grp_addr_len Group Address Length: Contains the byte length of the group or 
multicast address to be added. 

grp_addr Group Address: Contains the group or multicast address value to be 
added. 


Implementation Specifics 
This DLC_ADD_GRP ioctl operation for DLC is part of the device manager Data Link Control 
in BOS Extensions 2. 


insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information | 
Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 


IOCINFO ioctl Operation for DLC 


Returns a structure that describes the device (refer to the description of the sys/devinfo.h 
file. The first byte is set to an ioctype of DD_DLC. The subtype and data are defined by the 
individual DLC devices. See the /usr/include/sys/devinfo.h file for details. 
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Implementation Specifics 


This IOCINFO ioctl operation for DLC is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Ethernet (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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open, openx Subroutine Interface for Data Link Control (DLC) 
Devices 


Purpose 
Opens the GDLC device manager by special file name. 
Syntax 
#include <sys/fentl.h> 
#include <sys/gdlextcb.h> 
int open(path, oflag, mode) 
or 
int openx(path, oflag, mode, ext) 
char *path; 
int oflag; 
int mode; 
int ext; 
Description 
The open subroutine allows the application user to open a generic data link control (GDLC) 
device manager by specifying the DLC’s special file name and the target device handler’s 
special file name. Since the GDLC device manager is multiplexed, more than one process 
can open it (or the same process many times) and still have unique channel identifications. 
Each open carries the communications device handler’s special file name so that the DLC 
knows on which port to transfer data. This name must directly follow the DLC’s special file 
name. For example, in the /dev/dlcether/ent0 character string, ent0 is the special file 
name of the Ethernet device handler. GDLC obtains this name using its dlempx routine. 
Parameters 


path Consists of a character string containing the /dev special file name of the 
GDLC device manager, with the name of the communications device 
handler appended, as follows: 


/dev/dlcether/ent0o 


oflag Specifies a value for the file status flag. The GDLC device manager ignores 
all but the following flags: 


O_RDWR Open for reading and writing. This must be set for GDLC or 
the open will fail. 


O NDELAY, O NONBLOCK | 


Subsequent reads with no data present and writes that 
cannot get enough resources will return immediately. The 
calling process is not put to sleep. 


mode Specifies the O_CREAT mode parameter. This is ignored by GDLC. 
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ext Specifies the extended subroutine parameter. This is a pointer to the 
dic_open_ext extended I/O structure for the open subroutines. DLC 


Extended Parameters for open Subroutine provides more information on 
this parameter. 


Return Values 


Upon successful completion, the open subroutine returns a valid file descriptor that identifies 
the opened GDLC channel. 


If an error occurs, a value of —1 is returned with one of the following error numbers available 
using errno, as defined in the errno.h header file: 


ECHILD Cannot create a kernel process. 

EINVAL Invalid value. 

ENODEV No such device handler. 

ENOMEM Not enough resources to satisfy the open subroutine. 


EFAULT Kernel service, such as copyin or initp, has failed. 


Implementation Specifics 


This open subroutine interface is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
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The dicmpx routine. 
The copyin kernel service, initp kernel service. 
open, openx Subroutine, Extended Parameters. 
close Subroutine Interface for Data Link Control (DLC) Devices. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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open, openx Subroutine, Extended Parameters 


Description 
An extended open (openx) subroutine may be issued to alter certain normally defaulted 
parameters, such as maximum service access points (SAPs) and ring queue depths. Kernel 
users may change these normally defaulted parameters, but are required to provide 
additional parameters to notify the dlcopen routine that these callers are to be treated as 
kernel processes and not as application processes. Additional parameters passed include 
functional addresses that the user wishes GDLC to call for notification of asynchronous 
events, such as receive data available. 


The structure for the open subroutine extension parameters is as follows: 


struct dlc_open_ext 


{ 
ulong_t maxsaps; /* 1 (1 to 127) service access points * 
int (*rcevi_fa)(); /* receive I-frame function address */ 
int (*rcevx_fa)(); /* receive XID function address * / 
int (*rcvd_fa)(); /* receive Datagram function address ae 
int (*rcevn_fa)(); /* receive Network data function address */ 
int (*excp fa)(); /* exception handler function address x / 

}; 


See the /include/sys/gdlextcb.h file for more details on GDLC structures. 


The first parameter is optional for both the application and the kernel user. If the default 
value is desired, the field must be set to zero by the user prior to issuing the open 
subroutine. 


maxsaps Maximum SAPs: The maximum number of SAPs that this user 
channel is going to start and have running concurrently. The default 
is 1. Any value from 1 to 127 can be specified (0 gets the default). 


The last five parameters are mandatory for kernel users but are ignored by GDLC for 
application users. There are no default values. Each field must be filled in by the kernel user. 
All functional entry addresses must be valid. That is, entry points that the kernel user does 
not wish to support must at Jeast point to a routine that frees the communication’s memory 
buffer (mbuf) passed on the call. 


*revi_fa Receive |-Frame Data Function Pointer: The address of a user 
routine that handles the sequenced I-frame receive data 
completions. This field is valid for kernel users only and must be set 
to 0 (zero) by application users. 


*rcvx_fa Receive XID Function Pointer: The address of a user routine that 
handles the exchange ID receive data completions. 


*revd_fa Receive Datagram Function Pointer: The address of a user routine 
that handles the datagram receive data completions. 


*revn_fa Receive Network Data Function Pointer: The address of a user 
routine that handles the network receive data completions. 
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*excp_fa Exception Handler Function Pointer: The address of a user routine 


that handles the exception conditions, such as DLC_SAPE_RES 
(SAP Enabled) or DLC_CONT_RES (LS contacted). 


Implementation Specifics 


These DLC extended parameters for open subroutine are part of the device manager Data 
Link Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, |EEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The open, openx subroutine. 
The dicopen entry point routine. 
Parameter Blocks by ioctl Operation for DLC 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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Datagram Data Received Routine, for DLC 


Function 
This routine is coded by the kernel user and called by GDLC each time a datagram packet is 
received for the kernel user. 


Subroutine Call 
#include <sys/gdlextcb.h> 
int (*dlc_open_ext.rcvd_fa)(™m, ext) 
struct mbuf *m; 
struct dic_io_ ext *ext; 


Parameters 
m Specifies the pointer to a communications memory buffer (mbuf). 
ext Specifies the receive extension parameter. This is a pointer to the 
dic_io_ext extended 1/O structure for reads. 
Returns to GDLC 
int Indicates one of the following return codes from this function call: 
DLC_FUNC_OK The received datagram mbuf data has been 
accepted. 


DLC_FUNC_RETRY The received datagram mbuf data cannot be 
accepted at this time. GDLC should retry this 
function later. The actual retry wait period 
depends on the DLC in use. Excessive retries 
may close the link station. 


Implementation Specifics 
This DLC datagram data received routine is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
DLC Extended Parameters for read Subroutine. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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Exception Condition Routine 


Function 
This routine is coded by the kernel user and called by GDLC each time an asynchronous 


event occurs that must notify the kernel user, such as DLC_SAPD_RES (SAP disabled) or 
DLC_CONT_RES (contacted). 


Subroutine Call 
#include <sys/gdlextcb.h> 
int (*dic_open_ext.excp_fa)(ex/) 
struct dilc_getx_arg *ext; 


Parameter 


ext Specifies the same structure for a dic_getx_arg (get exception) ioctl 
subroutine. 


Returns to GDLC 
int Indicates the following return code from the function call: 
DLC_FUNC_OK The exception has been accepted. 


Note: The function call above has a hidden parameter extension for internal use only, 
defined as int *chanp, the channel pointer. 


Implementation Specifics 


This DLC exception condition routine is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The ioctl subroutine. 


Parameter Blocks by ioctl Operation for DLC. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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lI-Frame Data Received Routine 


Function 
This routine is coded by the kernel user and called by GDLC each time a normal sequenced 
data packet is received for the kernel user. 


Subroutine Call 
#include <sys/gdlextcb.h> 


int (*dic_open_ext.rcvi_fa)(m, ext) 
struct mbuf *m; 
struct dic_io_ext *ext; 


Parameters 
m Specifies the pointer to a communications memory buffer (mbuf). 
ext Specifies the receive extension parameter. This is a pointer to the 
dic_io_ext extended 1/O structure for reads. The argument to this 
parameter must be in the kernel space. 
Returns to GDLC 
int Indicates one of the following return codes from the function call: 
DLC_FUNC OK The received I-frame function call is accepted. 
DLC_FUNC_BUSY The received I-frame function call cannot be 


accepted at this time. The ioctl command 
operation DLC_EXIT_LBUSY must be issued 
later using the ioctl subroutine. 


DLC_FUNC_RETRY The received |-frame function call cannot be 
accepted at this time. GDLC should retry this 
function call later. The actual retry wait period 
depends on the DLC in use. Excessive retries 
can be subject to a halt of the link station. 


Implementation Specifics 
This DLC !-frame data received routine is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SOLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The ioctl subroutine. 


Parameter Blocks by ioctl Operation for DLC. 
DLC Extended Parameters for read Subroutine. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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Network Data Received Routine 


Function | 
This routine is coded by the kernel user and called by GDLC each time network- anecie data 
is received for the kernel user. 


Subroutine Call 
#include <sys/gdlextcb.h> 


int (*dilc_open_ext.rcvn_fa)(m, ext) 
struct mbuf *™m; 
struct dic_io_ext *ext; 


Parameters 
m Specifies the pointer to a communications memory buffer (mbuf). 
ext Specifies the receive extension parameter. This is a pointer to the 
dic_io_ext extended |/O structure for reads. 
Returns to GDLC 
int Indicates one of the following return codes from this function call: 
DLC_FUNC_OK The received network mbuf data has been 
accepted. 


DLC_FUNC_RETRY The received network mbuf data cannot be 
accepted at this time. GDLC should retry this 
function call some time later. The actual retry 
wait period depends on the DLC in use, and 
excessive retries can cause a disabling of the 
service access point. 


Implementation Specifics 
This DLC network data received routine is part of the device manager Data Link Control in 
BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
DLC Extended Parameters for read Subroutine. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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XID Data Received Routine 


Function 


This routine is coded by the kernel user and called by GDLC each time an exchange 
identification (XID) packet is received for the kernel user. 


Subroutine Call 
#include <sys/gdlextcb.h> 


int (*dic_open_ext.rcvx_fa)(m, ext) 
struct mbuf *m; 
struct dic_io_ext *ext,; 


Parameters 
m Specifies the pointer to a communication memory buffer (mbuf). 
ext Specifies the receive extension parameter. This is a pointer to the 
dic_io_ext extended I/O structure for reads. The argument to this 
parameter must be in the kernel space. 
Returns to GDLC 
int Indicates one of the following return codes from this function call: 
DLC_FUNC_OK The received XID mbuf data has been accepted. 


DLC_FUNC_RETRY The received XID mbuf data cannot be accepted 
at this time. GDLC should retry this function call 
some time later. The actual retry wait period 
depends on the DLC in use. Excessive retries 
may close the link station. 


implementation Specifics 


This DLC XID data received routine is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
DLC Extended Parameters for read Subroutine. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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read, readx Subroutine, Extended Parameters 


Description 
An extended read (readx) subroutine must be issued by an application user to provide 
GDLC with a structure to return the type of data and the service access point (SAP) and link 
station (LS) correlators. 
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The structure for the read subroutine extension parameters is as follows: 


struct dlc_io ext 


{ 
ulong_t sap corr; /* Sap correlator 
* / 
ulong_t ls_corr; /* Link Station correlator 
* / 
. ulong t flags; /* flags 
* / 
ulong_t dlh_len; /* data link header length 
* / 
}; 
sap_corr User SAP Correlator: The user’s SAP identifier of the received data. 
Is_corr User LS Correlator: The user’s LS identifier of the received data. 
flags Result Flags: The following flags are supported: 


#define DLC_INFO 
+/ 

#define DLC_XIDD 
a]. 

#define DLC_DGRM 
uid 

#define DLC_NETD 
*/ 

#define DLC_OFLO 
ed i 

#define DLC_RSPP 
# 


DLC_INFO 


DLC_XIDD 


0x80000000 /* normal I—frame 
0x40000000 /* XID data 

0x20000000 /* datagram 

0x10000000 /* network data 

0x00000002 /* receive overflow occurr 
0x00000001 /* response pending 


l-Frame Data Received: Indicates that normal sequenced data has 
been received for a link station. If buffer overflow (OFLO) is indicated, 
the received data has been truncated because the received data 


length exceeds either the maximum I-field size derived at completion 


of DLC_START_LS ioctl operation or the application user’s buffer 
size. 


XID Data Received: Indicates that exchange identification (XID) data 
has been received for a link station. If buffer overflow (OFLO) is 
indicated, the received XID has been truncated because the received 
data length exceeds either the maximum I-field size derived at 
DLC_START_LS completion or the application user’s buffer size. If 
response pending (RSPP) is indicated, an XID response is required 
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and must be provided to GDLC using a write XID as soon as possible 
to avoid repolling and possible termination of the remote LS. 


DLC_DGRM Datagram Data Received: Indicates that a datagram has been 
received for an LS. If buffer overflow (OFLO) is indicated, the 
received data has been truncated because the received data length 
exceeds either the maximum I-field size derived at DLC_START_LS 
completion or the application user’s buffer size. 


DLC_NETD Network Data: Indicates that data has been received from the 
network for a service access point. This may be link-establisnment 
data such as X.21 call-progress signals or smart modem command 
responses. It can also be data destined for the user’s SAP when no 
link station has been started that fits the addressing of the packet 
received. If buffer overflow (OFLO) is indicated, the received data 
has been truncated because the received data length exceeds either 
the maximum packet size derived at DLC_ENABLE_SAP completion 
or the application user’s buffer size. 


Network data contains the entire MAC layer packet, excluding any 
fields stripped by the adapter such as Preamble or CRC. 


DLC_OFLO Buffer Overflow: Indicates that overflow of the user data area has 
occurred and the data was truncated. This error does not set a 
u.u_error indication. 


DLC_RSPP Response Pending: This bit indicates that the XID received requires 
an XID response to be sent back to the remote link station. 


dih_len Data Link Header Length: This field has different meaning depending 
on whether the extension is for a readx subroutine call to GDLC ora 
response from GDLC. 


On the application readx subroutine it indicates whether the user 
wishes to have datalink header information prefixed to the data. If this 
field is set to 0 (zero), the data link header is not to be copied (only 
the I-field is copied). If this field is set to any nonzero value, the data 
link header information will be included in the read. 


On the response to an application readx subroutine this field contains 
the number of data link header bytes received and copied into the 
Data Link Header Information field. 


On asynchronous receive function handlers to the kernel user, this 
field contains the length of the data link header within the 
communications memory buffer (mbuf). 


Implementation Specifics 
These DLC extended parameters for read subroutine are part of the device manager Data 
Link Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 
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Related Information 
The read, readx, readv, or readvx Subroutine. 


DLC Extended Parameters for write Subroutine 
Parameter Blocks by ioctl Operation for DLC 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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readx Subroutine Interface for Data Link Control (dic) Devices 


Purpose 
Allows receive application data to be read using a file descriptor. 
Syntax 
#include <sys/gdlextcb.h> 
#include <sys/uio.h> 
int readx (fildes, buf, len, ext) 
int fildes; 
char *buf; 
int len; 
int ext; 
Description 
The receive queue for this application user is interrogated for any pending data. The oldest 
data packet is copied to user space, with the type of data, the link station correlator, and the 
service access point (SAP) correlator written to the extension area. When attempting to read 
an empty receive data queue, the default action is to delay until data is available. If the 
O_NDELAY or O_NONBLOCK flags are specified in the open subroutine, the readx 
subroutine returns immediately to the caller. 
Data is transferred using the uiomove kernel service between the user space and kernel 
communications memory buffers (mbufs). A complete receive packet must fit into the user’s 
read data area. GDLC does not break up received packets into multiple user data areas. 
Parameters 
fildes Specifies the file descriptor returned from the open subroutine. 
buf Points to the user data area. 
len Contains the byte count of the user data area. 
ext Specifies the extended subroutine parameter. This is a pointer to the 


dic_io_ext extended |/O structure for the readx subroutine. DLC Extended 
Parameters for read Subroutine provides more information on this 
parameter. 


Note: It is the user’s responsibility to set the ext parameter area to O (zero) 
prior to issuing the readx subroutine to insure valid entries when no 
data is available. 


Return Values 
Upon successful completion, the readx subroutine returns the number of bytes read and 
placed into the application data area. If more data is received from the media than will fit into 
the application data area, the DLC_OFLO flag is set in the dic_io_ext command extension 
area to indicate that the read is truncated. All excess data is lost. 


If no data is available and the application user has specified the O_NDELAY or 
O_NONBLOCK flags at open time, a zero is returned. 
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lf an error occurs, a value of —1 is returned with one of the following error numbers available 
using errno, as defined in the errno.h header file: 


EBADF Bad file number. 
EINTR A signal interrupted the subroutine before it received data. 
EINVAL Invalid value. 


ENOMEM Not enough resources to satisfy the read. 


Implementation Specifics 


This readx subroutine interface is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 


3-72 


The readxsubroutine, open subroutine. 
The uiomove kernel service. 
read, readx Subroutine, Extended Parameters . 


writex Subroutine Interface for Data Link. 
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select Subroutine Interface for Data Link Control (dic) Devices 


Purpose 
Allows data to be sent using a file descriptor. 


Syntax 
#include <sys/select.h> 
int select (nfdsmsgs, readlist, writelist, exceptlist, timeout) 
int nfdsmsgs; 
struct sellist *readlist, *writelist, *exceptlist; 
struct timeval * timeout; 


Description 
The select subroutine checks the specified file descriptor and message queues to see if 
they are ready for reading (receiving) or writing (sending), or if they have an exception 
condition pending. 


Note: GDLC does not support transmit for nonblocked notification in the full sense. If the 
writelist parameter is specified in the select call, GDLC always returns as if transmit 
is available. There is no checking to see if internal buffering is available or if internal 
control-block locks are free. These resources are much too dynamic, and tests for 
their availability can only be done reasonably at the time of use. 


The readlist and exceptlist parameters are fully supported. Whenever the selection criteria 
specified by the Se/Type parameter is true, the file system returns a value that indicates the 
total number of file descriptors and message queues that satisfy the selection criteria. The 
fdsmask bit masks are modified so that bits set to a value of 1 indicate file descriptors that 
meet the criteria. The msgids arrays are altered so that message queue identifiers that do 
not meet the criteria are replaced with a value of —1. If the selection is not satisfied, the 
calling process is put to sleep waiting on a selwakeup subroutine at a later time. 


Parameters 
nfdsmsgs Specifies the number of file descriptors and message queues to check. 


sellist The readlist, writelist, and exceptlist parameters specify what to check for 
during reading, writing, and exceptions, respectively. Each sellistis a 
structure that contains a file descriptor bit mask (fdsmask) and message 
queue identifiers (msgids). 


The writelist criterion is always set true by GDLC. 


timeout Points to a structure that specifies the maximum length of time to wait for at 
least one of the selection criteria to be met (if the timeout parameter is not a 
null pointer). 


Return Values 
Upon successful completion, the select subroutine returns a value that indicates the total 
number of file descriptors and message queues that satisfy the selection criteria. The return 
value is similar to the nfdsmsgs parameter in that the low-order 16 bits give the number of 
file descriptors, and the high-order 16 bits give the number of message queue identifiers. 
These values indicate the sum total that meet each of the read and exception criteria. 
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If the time limit specified by the timeout parameter expires, then the select subroutine 
returns a value of 0. 


lf an error occurs, a value of —1 is returned.with one of the following error numbers available 
‘using errno, as defined in the errno.h header file: 


EBADF Bad file number. 

EINTR A signal interrupted the subroutine before it found any of the selected. 
events. 

EINVAL One of the parameters contained an invalid value. 


Implementation Specifics 
This select subroutine interface is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The select subroutine. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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write, writex Subroutine, Extended Parameters 


Purpose 
An extended write (writex) subroutine must be issued by an application or kernel user to 
provide GDLC with the type of data and the service access point (SAP) and link station (LS) 
correlators. The structure for the write subroutine extension parameters is shown below: 


ulong_t sap corr; /* Sap correlator 
* / 
ulong t ls_corr; /* Link Station correlator 
*/ 
ulong t flags; /* flags 
*/ 
ulong_t dlh_len; /* <<< not used for writes >>> 
*/ 
}; 
sap_corr GDLC SAP Correlator: The user’s SAP identifier of the received data. 
Is_corr GDLC Link Station Correlator: The user’s link station identifier of the 
received data. . 
flags Write Flags: The following flags are supported: 
/*** Read and Write Flags ***/ 
#define DLC_INFO 0x80000000 /* normal I-—frame 
x / = 
#define DLC _XIDD 0x40000000 /* XID data 
*/ 
#define DLC_DGRM 0x20000000 /* datagram 
*/ 
#define DLC_NETD 0x10000000 /* network data 
*/ 
DLC_INFO Write Il-Frame Data: Requests a sequenced data class of information 


to be sent (generally called |-frames). 


This request is valid any time the target link station has been started 
and contacted. 


DLC_XIDD Write XID Data: Requests an exchange identification (XID) or 
response to be sent. 


This request is valid any time the target link station has been started 
with the following rules: 


GDLC sends the XID as a command as long as no DLC_TEST, 
DLC_CONTACT, DLC_HALT_LS, or DLC_XIDD write subroutine is 
already in progress, and no received XID is waiting for a response. If 
a received XID is waiting for a response, GDLC automatically sends 
the write XID as that response. If no response is pending and a 
command is already in progress, the write is rejected by GDLC. 


DLC_DGRM Write Datagram: Requests an unnumbered datagram to be sent. - 
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This request is valid any time the target link station has been started. 
DLC_NETD Write Network Data: Requests that network data be sent. 


Examples of network data include special modem control data or 
user-generated medium access control (MAC) and logical link control 
(LLC) headers. 


Network data must contain the entire MAC layer packet headers so 
that the packet can be sent without the data link control (DLC)’s 
intervention. GDLC only provides a pass-through function for this 
type of write. 


This request is valid any time the SAP is open. 


Implementation Specifics 


These DLC extended parameters for write subroutine are part of the device manager Data 
Link Control in BOS Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 


any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The write, writex subroutine. 
DLC Extended Parameters for read Subroutine. 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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writex 


writex Subroutine Interface for Data Link Control (dic) Devices 


Purpose 


Syntax 


Allows application data to be sent using a file descriptor. 


#include <sys/gdlextcb.h> 
#include <sys/uio.h> 


int writex (fildes, buf, len, ext) 
char *buf, 

int ext; 

int fildes, len; 


Description 


Four types of data can be sent to GDLC. Network data can be sent to a service access point 
(SAP), while normal, Exchange Identification (XID), or datagram data can be sent to a link 
station (LS). Data is transferred using the uiomove subroutine between the application user 
space and kernel communications |/O buffers (mbufs). All data must fit into a single packet 
for each write subroutine. The generic data link contro! (GDLC) does not separate the user's 
write data area into multiple transmit packets. A maximum write data size is passed back to 
the user at DLC_ENABLE_SAP completion and at DLC_START_LS completion for this 
purpose. See DLC_SAPE_RES and DLC_STAS_RES for further information. 


Normally, GDLC can immediately satisfy a write subroutine by completing the data link 
headers and sending the transmit packet down to the device handler. In some cases, 
however, transmit packets can be blocked by the particular protocol’s flow control or by a 
resource outage. GDLC reacts to this differently based on the systems blocked or 
nonblocked file status flags. These are set for each channel using the O_NDELAY and 
O_NONBLOCK values passed on open subroutines or on fentl subroutines with the 
F_SETFD parameter. 


GDLC only looks at the uio_fmode on each write subroutine to determine whether the 
operation is blocked or nonblocked. Nonblocked writes that cannot get enough resources to 
queue the data return an error indication. Blocked write subroutines put the calling process 
to sleep until the resources free up or an error occurs. 


Note: GDLC does not support nonblocked transmit users based on resource availability 
using the selwakeup subroutine. Internal resources such as communications I/O 
buffers and control block locks are very dynamic. Any write subroutines that fail with 
errors (such as EAGAIN or ENOMEM) should be retried at the users discretion. 


Parameters 


fildes Specifies the file descriptor returned from the open subroutine. 
buf Points to the user data area. 
len Contains the byte count of the user data area. 


ext Specifies the extended subroutine parameter. This is a pointer to the 
dic_io_ext extended I/O structure for the writex subroutine. DLC Extended 
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Parameters for write subroutine provides more information on this 
parameter. 


Return Values 
Upon successful completion, this service returns the number of bytes that were written into a 
communications packet from the user data area. 


If an error occurs, a value of —1 is returned with one of the following error numbers available 
using errno, as defined in the errno.h header file. 


EAGAIN Not enough resources to satisfy the write; for example, unable to obtain a 
necessary lock. The user can try again later. 

EBADF Bad file number. 

EINVAL Invalid value, such as too much data for a single packet. 

EIO An I/O error has occurred, such as loss of the port. 

ENOMEM Not enough resources to satisfy the write; for example, a lack of 


communications memory buffers (mbufs). The user can try again later. 


Implementation Specifics 
This writex subroutine interface is part of the device manager Data Link Control in BOS 
Extensions 2. 


Insert the Standard Ethernet, SDLC, Token-Ring, IEEE Etherent (802.3), or X.25 QLLC (or 
any combination) in place of device manager above, depending on which device manager 
you decide to use. 


Related Information 
The writex subroutine, uiomove subroutine, fentl subroutine, open subroutine. 
DLC Extended Parameters for write Subroutine 
readx Subroutine Interface for Data Link Control (dic) Devices 
Parameter Blocks by ioctl Operation for DLC 


Generic Data Link Control (GDLC) Environment Overview in Communications Programming 
Concepts. 
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lb $lookup_interface Library Routine (NCS) 


Purpose 


Looks up information about an interface in the GLB database. 


Syntax 


void Ib_$lookup_interface (object_interface, lookup_handle, max_results, num_results, 


results, status) 


uuid_$t *object_interface; 


Ib_$lookup_handle_t */ookup_handle; 
unsigned long max_results; 
unsigned long *num_results; 


Ib_$Sentry_t results [ ]; 
status_$t *status; 


Parameters 
Input 


object_interface 


max_results 


Input/Output 
lookup_handle 


Output 


num_results 


results 


Status 


Points to the UUID of the interface being looked up. 


Specifies the maximum number of matching entries that can be 
returned by a single call. This should be the number of elements 
in the results parameter array. 


Specifies a location in the database. On input, the lookup_handle 
value indicates the location in the database where the search 
begins. An input value of Ib_$default_lookup_ handle specifies 
that the search starts at the beginning of the database. 


On return, the jookup_handle parameter indicates the next 
unsearched part of the database (that is, the point at which the 
next search should begin). A return value of 
lb_$default_lookup_handle indicates that the search reached 
the end of the database. Any other value indicates that the 
search found at most the number of matching entries specified by 
the max_results parameter before it reached the end of the 
database. 


Points to the number of entries that are returned in the results 
parameter array. 


Specifies the array that contains the matching GLB database 
entries, up to the number specified in the max_results parameter. 
If the array contains any entries for servers on the local network, 
those entries appear first. 


Points to the completion status. 
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Description 
The Ib_$lookup_interface routine returns GLB database entries whose object_interface | 


fields match the specified interface. It returns information about all replicas of all objects that 
can be accessed through that interface. 


The Ib_$lookup_interface routine cannot return more than the number of matching entries 
specified by the max_results parameter at one time. The lookup_handle parameter directs 
this routine to do sequential lookup calls to find all matching entries. 


Notes: 


1. The Location Broker does not prevent modification of the database between 
lookup calls, which can cause the locations of entries relative to a lookup_handle 
value to change. If multiple calls are made to find all matching results in the 
database, the returned information may skip or duplicate entries from the 
database. 


2. It is also possible for the results of a single lookup call to skip or duplicate entries. 
This can occur if the size of the results exceeds the size of an RPC packet (64K 
bytes). 


Example 


1. To look up information in the GLB database about a matrix multiplication interface, use 
the following: 


lb _ $lookup_interface (&matrix_if_id, &lookup_handle, 
results array size, &num_results, 
&matrix_if results _array, &status); 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


4—4 Base Operating System Reference 


Ib_ $lookup_ object 


Ib S$lookup object Library Routine (NCS) 


Purpose 
Looks up information about an object in the GLB database. 
Syntax 
void |b _$lookup_ object (object, lookup_handle, max_results, num_results, results, status) 
uuid_$t *object; 
Ib_$lookup_handle_t */ookup_handle; 
unsigned long max_results; 
unsigned long *num_results; 
Ib_$entry_t results [ ]; 
Status_$t “status; 
Parameters 
Input 
object Points to the UUID of the object being looked up. 
max_results Specifies the maximum number of matching entries that can be 
returned by a single call. This should be the number of elements 
in the results parameter array. 
Input/Output 
lookup_handle Specifies a location in the database. On input, the value of the 
lookup_handle parameter indicates the location in the database 
where the search begins. An input value of 
lb_$default_lookup_handle specifies that the search starts at 
the beginning of the database. 
On return, the lookup_handle parameter indicates the next 
unsearched part of the database (that is, the point at which the 
next search should begin). A return value of 
Ib_ $default_lookup_handle indicates that the search reached 
the end of the database. Any other value indicates that the 
search found at most the number of matching entries specified by 
the max_results parameter before it reached the end of the 
database. 
Output 
num_results Points to the number of entries that were returned in the results 
parameter array. 
results Specifies the array that contains the matching GLB database 
entries, up to the number specified in the max_results parameter. 
If the array contains any entries for servers on the local network, 
those entries appear first. 
Status Points to the completion status. 
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Description 
The Ib_$lookup_object routine returns GLB database entries whose object fields match 


the specified object. It returns information about all replicas of an object and ail interfaces to 
the object. 


The Ib_$lookup_object routine cannot return more than the number of matching entries 
specified by max_results parameter at one time. The jookup_handle parameter directs this 
routine to do sequential lookup calls to find all matching entries. 


Notes: 


1. The Location Broker does not prevent modification of the database between 
lookup calls, which can cause the locations of entries relative to a value of the 
lookup_handle parameter to change. If multiple calls are made to find all matching 
results in the database, the returned information may skip or duplicate entries from 
the database. 


2. It is also possible for the results of a single lookup call to skip or duplicate entries. 
This can occur if the size of the results exceeds the size of an RPC packet (64K 
bytes). 


Example 
1. To look up GLB database entries for the bank bank_id, enter the following: 


lb_S$lookup_object(&bank_id, &lookup_handle, MAX _LOCS, &n_locs, 
bank_loc, &st); 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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Ib_$lookup_object_local Library Routine (NCS) 


Purpose 
Looks up information about an object in an LLB database. 
Syntax 
void Ib_$lookup_object_local (object, sockaddr, slength, lookup_handle, max_results, 
num_results, results, status) 
uuid_$t *object; 
socket_$addr_t *sockadadr, 
unsigned long s/ength; 
Ib_ $lookup_handle_t */ookup_handle; 
unsigned long max_results; 
unsigned long *num_results; 
Ib_$entry_t results [ }; 
status_$t *status; 
Parameters 
Input 
object Points to the UUID of the object being looked up. 
sockaddr Specifies the location of the LLB database to be searched. The 
socket address must specify the network address of a host. 
However, the port number in the socket address is ignored. The 
lookup request is always sent to the host’s LLB port. 
slength Specifies the length, in bytes, of the socket address specified by 
the sockaddr parameter. 
max_results Specifies the maximum number of matching entries that can be 
returned by a single call. This should be the number of elements 
in the results parameter array. 
Input/Output 
lookup_handle Specifies a location in the database. On input, the value of the 


lookup_handle parameter indicates the location in the database 
where the search begins. An input value of 
lb_$default_lookup_handle specifies that the search starts at 
the beginning of the database. 


On return, the jookup_handle indicates the next unsearched part 
of the database (that is, the point at which the next search should 
begin). A return value of Ib_$default_lookup_handle indicates 
that the search reached the end of the database. Any other value 
indicates that the search found at most the number of matching 
entries specified by the max_results parameter before it reached 
the end of the database. 
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Output 
num_results Points to the number of entries that were returned in the results 
. parameter array. 

results Specifies the array that contains the matching GLB database 
entries, up to the number specified in the max_results parameter. 
lf the array contains any entries for servers on the local network, 
those entries appear first. 

Status Points to the completion status. 

Description 


The Ib_$lookup_object_local routine searches the specified LLB database and returns all 
entries whose object fields match the specified object. It returns information about all 
replicas of an object and all interfaces to the object that are located on the specified host. 


The Ib_$lookup_interface routine cannot return more than the number of matching entries 
specified by the max_results parameter at one time. The lookup_handle parameter directs 
this routine to do sequential lookup calls to find all matching entries. 


Notes: 


1. The Location Broker does not prevent modification of the database between 
lookup calls. This can cause the locations of entries relative to a value of the 
lookup_handle parameter to change. If multiple calls are made to find all matching 
results in the database, the returned information may skip or duplicate entries from 
the database. 


2. It is also possible for the results of a single lookup call to skip or duplicate entries. 
This can occur if the size of the results exceeds the size of an RPC packet (64K 
bytes). 


Example 
1. In the following example, the repob object is replicated, with only one replica located on 
any host. To look up information about the repob object, enter the following: 


lb_$lookup_object_local (&repob_id, &location, location_length, 
&lookup_handle, 1, &num_results, myob_entry, &st); 


Since there is only one replica located on any host, the routine returns at most one result. 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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lb $lookup_range Library Routine (NCS) 


Purpose 
Looks up information in a GLB or LLB database. 
Syntax 
void Ib_$lookup_range (object, object_type, object_interface, location, lookup_handle, 
location_length, max_results, num_results, results, status) 
uuid_$t *object; 
uuid_$t *object_type; 
uuid_$t *object_interface; 
socket_$addr_t */ocation; 
unsigned long /ocation_length; 
Ib_$lookup_handle_t */ookup_handle; 
unsigned long max_results; 
unsigned long *num_results; 
Ib_$entry_t results [ J; 
status_$t *status; 
Parameters 
Input 
object Points to the UUID of the object being looked up. 
object_type Points to the UUID of the type being looked up. 
object_interface Points to the UUID of the interface being looked up. 
location Points to the location of the database to be searched. If the value 
of the /ocation_length parameter is 0, the GLB database is 
searched. Otherwise, the LLB database at the host specified by 
the socket address is searched. If the LLB database is searched, 
the port number in the socket address is ignored, and the lookup 
request is sent to the LLB port. 
location_length Specifies the length, in bytes, of the socket address indicated by 
the location parameter. A value of 0 indicates that the GLB 
database is to be searched. 
max_results Specifies the maximum number of matching entries that can be 


returned by a single call. This should be the number of elements 
in the results array. 
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Input/Output 


lookup_handle Specifies a location in the database. On input, the value of the 
lookup_handle parameter indicates the location in the database 
where the search begins. An input value of 
Ib_ $default_lookup_handle specifies that the search starts at 
the beginning of the database. 


On return, the jookup_handle parameter indicates the next 
unsearched part of the database (that is, the point at which the 
next search should begin). A return value of 

Ib_ $default_lookup_handle indicates that the search reached 
the end of the database. Any other value indicates that the 
search found at most the number of matching entries specified by 
the max_results parameter before it reached the end of the 
database. 


Output 


num_results Points to the number of entries that were returned in the results 
parameter array. 


results Specifies the array that contains the matching GLB database 
entries, up to the number specified in the max_results parameter. 
If the array contains any entries for servers on the local network, 
those entries appear first. 


status Points to the completion status. 


Description 
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The Ib_$lookup_range routine returns database entries that contain matching object, 
obj_type, and obj_interface identifiers. A value of uuid_$nil in any of these input 
parameters acts as a wild card and matches all values in the corresponding entry field. You 
can include wild cards in any combination of these parameters. 


The Ib_$lookup_interface routine cannot return more than the number of matching entries 
specified by the max_results parameter at one time. The lJookup_handle parameter directs 
this routine to do sequential lookup calls to find all matching entries. 


Notes: 


1. The Location Broker does not prevent modification of the database between 
lookup calls, which can cause the locations of entries relative to a value of the 
lookup_handle parameter value to change. If multiple calls are made to find all 
matching results in the database, the returned information may skip or duplicate 
entries from the database. 


2. It is also possible for the results of a single lookup call to skip or duplicate entries. 
This can occur if the size of the results exceeds the size of an RPC packet (64K 
bytes). 
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Example 


1. To look up information in the GLB database about the change_if interface to the 
proc_db2 object (which is of the proc_db type), enter the following: 


lb S$lookup_range (&proc_db2_id, &proc_db_ id, &change_if id, 
glb, 0, &lookup_handle, 10, &num_results, results, &st); 


The name glb is defined elsewhere as a null pointer. The results parameter is a 
10-element array of the Ib_$entry_t type. 


implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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Ib_$lookup_type Library Routine (NCS) 


Purpose 
Looks up information about a type in the GLB database. 
Syntax 
void Ib_$lookup_type (object_type, lookup_handle, max_results, num_results, results, 
status) 
uuid_$t *object_type; 
Ib_$lookup_handle_t */ookup_handle; 
unsigned long max_results; 
unsigned long *num_results; 
Ib_$entry_t results [ ]; 
status_$t *status; 
Parameters 
Input 
object_type Points to the UUID of the type being looked up. 
max_results Specifies the maximum number of matching entries that can be 
returned by a single call. This should be the number of elements 
in the results parameter array. 
Input/Output 
lookup_handle Specifies a location in the database. On input, the value of the 
lookup_handle parameter indicates the location in the database 
where the search begins. An input value of 
Ib_$default_lookup_handle specifies that the search starts at 
the beginning of the database. 
On return, the jookup_handle parameter indicates the next 
unsearched part of the database (that is, the point at which the 
next search should begin). A return value of 
Ib $default_lookup_handle indicates that the search reached 
the end of the database. Any other value indicates that the 
search found at most the number of matching entries specified by 
the max_results parameter before it reached the end of the 
database. 
Output 
num_results Points to the number of entries that were returned in the results 
parameter array. 
results ‘ Specifies the array that contains the matching GLB database 
entries, up to the number specified in the max_results parameter. 
If the array contains any entries for servers on the local network, 
those entries appear first. 
Status Points to the completion status. 
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Description 
The Ib_$lookup_type routine returns GLB database entries whose obj_type fields match 


the specified type. It returns information about all replicas of all objects of that type and 
about all interfaces to each object. 


The Ib_$lookup_type routine cannot return more than the number of matching entries 
specified by the max_results parameter at one time. The lookup_handle parameter directs 
this routine to do sequential lookup calls to find all matching entries. 


Notes: 


1. The Location Broker does not prevent modification of the database between 
lookup calls, which can cause the locations of entries relative to a value of the 
lookup_handle parameter to change. If multiple calls are made to find all matching 
results in the database, the returned information may skip or duplicate entries from 
the database. 


2. It is also possible for the results of a single lookup call to skip or duplicate entries. 
This can occur if the size of the results exceeds the size of an RPC packet (64K 
bytes). 


Example 


1. To look up information in the GLB database about the array_proc type, enter the 
following: 


lb_Slookup_type (&array_proc_id, &lookup handle, 10, 
&num_results, &results, &st) 


The results parameter is a 10-element array of the Ib $entry_t type. 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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Ib_$register Library Routine (NCS) 


Purpose 
Registers an object and an interface with the Location Broker. 
Syntax 
void Ib_$register (object, object_type, object_interface, flags, annotation, sockaddr, 
slength, entry, status) 
uuid_$t *object; 
uuid_$t *object_type; 
uuid_$t *object_interface; 
b_ $server_flag_t *flags; 
char annotation [ ]; 
socket_$addr_t *sockaddr; 
unsigned long s/ength; 
lb_$entry_t *entry; 
status_$t ‘status; 
Parameters 
Input 
object Points to the UUID of the object being looked up. 
object_type Points to the UUID of the type being looked up. 
object_interface Points to the UUID of the interface being looked up. 
flags Points to the server that implements the interface. The value 
must be 0 or Ib_$server_flag_local. 
annotation Specifies information, such as textual descriptions of the object 
and the interface. It is set in a 64-character array. 
sockaddr Points to the socket address of the server that exports the 
interface to the object. 
slength Specifies the length, in bytes, of the socket address (sockaddr). 
Output 
entry Points to the copy of the entry that was entered in the Location 
Broker database. 
status Points to the completion status. 
Description 


The Ib_$register routine registers with the Location Broker a specific interface to an object 
and the location of a server that exports that interface. This routine replaces an existing 
entry in the Location Broker database that matches the object, object_type, and 
object_interface parameters as well as both the address family and host in the socket 
address specified by the sockaddr parameter. If no such entry exists, the routine adds a new 
entry to the database. 
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If the flags parameter has a value of Ib_$server_flag_local, the entry is registered only in 
the LLB database at the host where the call is issued. Otherwise, the entry is registered in 
both the LLB and the GLB databases. 


Example 
1. To register the bank interface to the bank_id object, enter the following: 


lb S$register (&bank_id, &bank_Suuid, &bank_S$if_spec.id, 0, 
BankName, &saddr, slen, &entry, &st); 


Implementation Specifics 
This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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Ib $unregister Library Routine (NCS) 


Purpose 
Removes an entry from the Location Broker database. 

Syntax 
void Ib_$unregister (entry, status) 
Ib_$entry_t *entry; 
status_$t *status; 

Parameters 
Input 
entry Points to the entry being removed from the Location Broker database. 
Output 
Status Points to the completion status. 

Description | 
The Ib_$unregister routine removes from the Location Broker database the entry that 
matches the value supplied in the entry parameter. The value of the entry parameter should 
be identical to that returned by the Ib_$register routine when the database entry was 
created. However, the Ib_$unregister routine does not compare all of the fields in the entry 
parameter. It ignores the flags field, the annotation field, and the port number in the saddr 
field. 
This routine removes the entry from the LLB database on the local host (the host that issues 
the call). If the flags field of the entry parameter is not the value Ib_$server_flag_local, this 
routine also removes the entry from all replicas of the GLB database. 

Example 


1. To unregister the entry specified by the BankEntry results structure, which was obtained 
from a previous call to the Ib_$register routine, enter the following: 


lb Sunregister (&BankEntry, &st); 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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pfm_$cleanup Library Routine (NCS) 


Purpose 
Establishes a cleanup handler. 
Syntax 
#include <idl/c/base.h> 
#include <idl/c/pfm.h> 
status_$t 
pfm_$cleanup(cleanup_record) 
pfm_$cleanup_rec *cleanup_record; 
Parameters 
Input 
cleanup_record A record of the context in which the pfm_$cleanup routine is called. A 
program should treat this as an opaque data structure and not try to 
alter or copy its contents. It is needed by the pfm_$cleanup and 
pfm_$reset_cleanup routines to restore the context of the ealing 
process at the cleanup handler entry point. 
Description 


The pfm_$cleanup routine establishes a cleaunup handler that is executed when a fault 
occurs. A cleaunup handler is a piece of code executed before a program exits when a 
signal is received by the process. The cleaunup handler begins with a call to the 
pfm_$cleanup routine. This routine registers an entry point with the system where program 
execution resumes when a fault occurs. When a fault occurs, execution resumes after the 
most recent call to the pfm_$cleanup routine. 


There can be more than one cleaunup handler in a program. Multiple cleaunup handlers are 
executed consecutively on a last-in/first-out basis, starting with the most recently established 
handler and ending with the first cleaunup handler. The system provides a default cleaunup 
handler established at program invocation. The default cleaunup handler is always called 
last, just before a program exits, and releases any system resources still held before 
returning contro! to the process that invoked the program. 


When called to establish a cleaunup handler, the pfm_$cleanup routine returns the 
pfm_$cleanup_set status to indicate that the cleaunup handler was successfully 
established. When the cleaunup handler is entered in response to a fault signal, the 
pfm_$cleanup routine effectively returns the value of the fault that triggered the handler. 


Note: Cleanup handler code runs with asynchronous faults inhibited. When the 
pfm_$cleanup routine returns something other than pfm_$cleanup_set status, 
which indicates that a fault has occurred, there are four possible ways to leave the 
clean_up code: 


e The program can call the pfm_$signal routine to start the next cleaunup handler 
with a different fault signal. 


e The program can call the pfm_$exit routine to start the next cleaunup handler 
with the same fault signal. 
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e The program can continue with the code following the cleaunup handler. It should 
generally call the pfm_$enable routine to re-enable asynchronous faults. 
Execution continues from the end of the cleaunup handler code; it does not 
resume where the fault signal was received. 


e The program can re-establish the handler by calling the pfm_$reset_cleanup 
routine before proceeding. 


Example 
1. To establish a cleaunup handler for a routine, use the following: 


fst = pfim_cleanup(crec) 


where fst is of type status_$t and crec is of type pfm_$cleanup_crec. 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The pfm_$signal routine. 
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pfm_$enable Library Routine (NCS) 


Purpose 
Enables asynchronous faults. 

Syntax 
#include <idl/c/base.h> 
#include <idl/c/pfm.h> 
void 
pfm_$enable (void) 

Description 
The pfm_$enable routine enables asynchronous faults after they have been inhibited by a 
call to the pfm_$inhibit routine. The pfm_$enable routine causes the operating system to 
pass asynchronous faults on to the calling process. 
While faults are inhibited, the operating system holds at most one asynchronous fault. 
Consequently, when pfm_$enable returns, there can be at most one fault waiting on the 
process. If more than one fault was received between calls to the pfm_$inhibit and 
pfm_$enable routines, the process receives the first asynchronous fault received while 
faults were inhibited. 

Example 


1. To enable asynchronous interrupts to occur after a call to the pfm_$inhibit routine, use 
the following: 


pfm_Senable( ); 


Implementation Specifics 
This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The pfm_$enable_faults routine, pfm_$inhibit routine. 
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pfm_$enable_faults Library Routine (NCS) 


Purpose 
Enables asynchronous faults. 

Syntax 
#include <idl/c/base.h> 
#include <idl/c/pfm.h> 
void 
pfm_$enable_faults (void) 

Description 
The pfm_$enable_faults routine enables asynchronous faults after they have been 
inhibited by a call to the pfm_$inhibit_faults routine. The pfm_$enable_faults routine 
causes the operating system to pass asynchronous faults on to the calling process. 
While faults are inhibited, the operating system holds at most one asynchronous fault. 
Consequently, when pfm_$enable_faults returns, there can be at most one fault waiting on 
the process. If more than one fault was received between calls to the pfm_$inhibit_faults 
and pfm_$enable_faults routines, the process receives the first asynchronous fault 
received while faults were inhibited. 

Example 


1. To enable faults to occur after a call to pfm_$inhibit_faults, use the following: 


pfm_Senable faults( ); 


Implementation Specifics 3 
This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The pfm_$enable routine, pfm_Sinhibit_faults routine. 
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pfm_$inhibit Library Routine (NCS) 


Purpose 
Inhibits asynchronous faults. 

Syntax 
#include <idl/c/base.h> 
#include <idl/c/pfm.h> 
void 
pfm_$inhibit (void) 

Description 
The pfm_S$inhibit routine prevents asynchronous faults from being passed to the calling 
process. While faults are inhibited, the operating system holds at most one asynchronous 
fault. Consequently, a call to the pfm_$inhibit routine can result in the loss of some signals. 
For that and other reasons, it is good practice to inhibit faults only when absolutely 
necessary. 
Note: This routine has no effect on the processing of synchronous faults, such as access 

violations or floating-point and overflow exceptions. 
Example 


1. To prevent asynchronous interrupts from occurring in a critical portion of a routine, use 
the following: 


pfm_Sinhibit( ); 
Implementation Specifics 
This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The pfm_$enable routine, pfm_$inhibit_faults routine. 
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pfm_$inhibit_faults Library Routine (NCS) 


Purpose 
Inhibits asynchronous faults, but allows task switching. 


Syntax 


#include <idl/c/base.h> 
#include <idl/c/pfm.h> 


void 
pfm_S$inhibit_faults (void) 


Description 
The pfm_$inhibit routine prevents asynchronous faults, except for time-sliced task 
switching, from being passed to the calling process. While faults are inhibited, the operating 
system holds at most one asynchronous fault. Consequently, a call to the 
pfm_S$inhibit_faults routine can result in the loss of some signals. For that and other 
reasons, it is good practice to inhibit faults only when absolutely necessary. 


Note: This routine has no effect on the processing of synchronous faults, such as access 
violations or floating-point and overflow exceptions. 
Example : 
1. To prevent faults from occurring in a critical portion of a routine, use the following: 
pfm_Sinhibit_faults( ); 
Implementation Specifics 
This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The pfm_$enable_faults routine, pfm_$inhibit routine. 
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pfm_$init Library Routine (NCS) 


Purpose 
Initializes the program fault management (PFM) package. 
Syntax 
#include <idl/c/base.h> 
#include <idl/c/pfm.h> 
void 
pfm_S$init (flags) 
unsigned long flags; 
Parameters 
Input 
flags Indicates which initialization activities to perform. Currently only one value is 
valid: pfm_$init_signal_handlers. This causes C signals to be intercepted 
and converted to PFM signals. The signals intercepted are SIGINT, 
SIGILL, SIGFPE, SIGTERM, SIGHUP, SIGQUIT, SIGTRAP, SIGBUS, 
SIGSEGV, and SIGSYS. 
Description 
The pfm_$init routine initializes the PFM package. Applications that use the PFM package 
should invoke the pfm_$init routine before invoking any other NCS routines. 
Example 


1. To initialize the PFM subsystem, use the following: 
pfm_Sinit(pfm_S$init_signal_ handlers); 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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pfm._$reset_cleanup Library Routine (NCS) 


Purpose 
Resets a cleanup handler. 
Syntax 
#include <idl/c/base.h> 
#include <idl/c/pfm.h> 
void 
pfm_$reset_cleanup (cleanup_record, status) 
pfm_$cleanup_rec *cleanup_record; 
status $t ‘status; 
Parameters 
Input 
cleanup_ record A record of the context at the cleanup handler entry point. It is supplied 
by the pfm_$cleanup routine when the cleanup handler is first 
established. 
Output 
Status Points to the completion status. 
Description 
The pfm_$reset_cleanup routine re-establishes the cleanup handler last entered so that 
any subsequent errors enter it first. This procedure should only be used within cleanup 
handler code. 
Example 


1. To re-establish a cleanup handler, use the following: 
pfm_Sreset_cleanup(crec, st); 
where the crec cleanup record is a valid cleanup handler. 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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pfm_$rls_cleanup Library Routine (NCS) 


Purpose 
Releases cleanup handlers. 


Syntax 
#include <idl/c/base.h> 
#include <idl/c/pfm.h> 


void 

pfm_$ris_cleanup(cleanup_record, status) 
pfm_$cleanup_rec *cleanup_record; 
status $t *status; 


Parameters 
Input 


cleanup_record The cleanup record for the first cleanup handler to release. 


Output 


Status Points to the completion status. If the status parameter has a value of 
pfm_$bad_rls_order, it means that the caller attempted to release a 
cleanup handler before releasing all handlers established after it. This 
status is only a warning. The intended cleanup handler is released, 
along with all cleanup handlers established after it. 


Description 
The pfm_$rls_cleanup routine releases the cleanup handler associated with the 
cleanup_record parameter and all cleanup handlers established after it. 


Example 
1. To release an established cleanup handler, use the following: 


pfm_$rils_cleanup(crec, st); 
where crec is a valid cleanup record established by the pfm_$cleanup routine. 
implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Network Computing System (NCS) 4—25 


pfm_$signal 


pfm_$signal Library Routine 


Purpose 
Signals the calling process. 


Syntax 
#include <idl/c/base.h> 
#include <idl/c/pfm.h> 


void 


pfm_$signal (fau/t_signah 
status_$t *fault_signal; 


Parameters 

Input 

fault_ signal A fault code. 
Description 


The pfm_$signal routine signals the fault specified by the faul/t_signal/ parameter to the 
calling process. It is usually called to leave cleanup handlers. 


Note: This routine does not return when successful. 


Example 
1. To send the calling process a fault signal, use the following: 
pfm_Ssignal(fst); 


where fst is a valid PFM fault. 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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rpc_$alloc_handle Library Routine (NCS) 


Purpose 
Creates an RPC handle. 
Syntax 
handle_t rpc_$alloc_handle (object_id, family, status) 
uuid_$t *object_id; 
unsigned long family; 
Status_$t “status; 
Parameters 
Input 
object_id Points to the UUID of the object to be accessed. If there is no specific 
object, specify uuid_$nil as the value. 
family Specifies the address family to use in communications to access the object. 
Output 
Status Points to the completion status. 
Description 


The rpc_$alloc_handle routine creates an unbound RPC handle that identifies a particular 
object but not a particular server or host. A remote procedure call made using an unbound 
handle is broadcast to all Local Location Brokers (LLBs) on the local network. If the call’s 
interface and the object identified by the handle are both registered with any LLB, that LLB 
forwards the request to the registering server. The client RPC runtime library returns the first 
response that it receives and binds the handle to the server. 


Note: This routine is used by clients only. 


Return Value 


Example 


Upon successfu! completion, the rpc_$alloc_handle routine returns an RPC handle 
identifying the remote object in the form handle_t. This handle is used as the first input 
parameter to remote procedure calls with explicit handles. 


The following statement allocates a handle that identifies the Acme company’s payroll 
database object: 


handle = rpc_$alloc_handle (&acme_pay id, socket_$dds, &st); 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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rpc_$bind Library Routine (NCS) 


Purpose 
Allocates an RPC handle and sets its binding to a server. 
Syntax 
handie_t rpc_$bind (object_id, sockaddr, slength, status) 
uuid_$t *object_id; 
socket_$addr_t *sockadadr, 
unsigned long s/ength; 
us_$t *status; 
Parameters 
Input 
object_id Points to the UUID of the object to be accessed. If there is no specific 
object, specify uuid_$nil as the value. 
sockaddr Points to the socket address of the server. 
slength Specifies the length, in bytes, of the socket address (sockaddr). 
Output 
status Points to the completion status. 
Description 


The rpce_$bind function creates a fully bound RPC handle that identifies a particular object 
and server. This routine is equivalent to an rpc_$alloc_handle routine followed by an 
rpc_$set_binding routine. 


Note: This routine is used by clients only. 


Return Value 
Upon successful completion, this routine returns an RPC handle (handle_t) that identifies 


the remote object. This handle is used as the first input parameter to remote procedure calls 
with explicit handles. 


Example 


The following example binds a banking client program to the specified object and socket 
address: 


h = rpc_$bind(&bank_id, &bank_loc[{0].saddr, bank_loc[0].saddr_len, 
&st); 


The bank_loc structure is the results parameter of a previous Location Broker lookup call. 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The rpce_$alloc_handle routine, rpc_$set_binding routine. 
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rpc_$clear_binding Library Routine (NCS) 


Purpose 
Unsets the binding between an RPC handle and a host and server. 

Syntax 
void rpc_$clear_binding (handle, status) 
handle_t handle; 
status_$t *status; 

Parameters 
Input 
handle Specifies the RPC handle from which the binding is being cleared. 
Output 
Status Points to the completion status. 

Description 
The rpe_$clear_binding routine removes any association between an RPC handle and a 
particular server and host, but does not remove the association between the handle and an 
object. This routine saves the RPC handle so that it can be reused to access the same 
object, either by broadcasting or after resetting the binding to another server. 
A remote procedure call made using an unbound handle is broadcast to all Local Location 
Brokers (LLBs) on the local network. If the call’s interface and the object identified by the 
handle are both registered with any LLB, that LLB forwards the request to the registering 
server. The client RPC runtime library returns the first response that it receives and binds the 
handle to the server. 
The rpc_$clear_binding routine reverses an rpc_$set_binding routine. 
Note: This routine is used by clients only. 

Example 


To clear the binding represented in a handle, enter the following: 


rpc _ S$clear_binding(handle, &st); 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The rpc_$set_binding routine. 
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rpc_$clear_server_binding Library Routine (NCS) 


Purpose 


Syntax 


Unsets the binding between an RPC handle and a server. 


void rpc_$clear_server_binding (handle, status) 
handle_t handle; 
status _$t *status; 


Parameters 


Input 


handle Specifies the RPC handle from which the server binding is being cleared. 


Output 


status Points to the completion status. 


Description 


Example 


The rpc_$clear_server_binding routine removes the association between an RPC handle 
and a particular server (which is a particular port number), but does not remove the 
associations with an object and a host. For example, the routine unmaps the handle to the 
port number, but it leaves the object and host associated through a network address. 


This routine replaces a fully bound handle with a bound-to-host handle. A bound-to-host 
handle identifies an object located on a particular host, but does not identify a server 
exporting an interface to the object. 


if a client uses a bound-to-host handle to make a remote procedure call, the call is sent to 
the Local Location Broker (LLB) forwarding port at the host identified by the handle. If the 
call’s interface and the object identified by the handle are both registered with the host's 
LLB, the LLB forwards the request to the registering server. When the client RPC runtime 
library receives a response, it binds the handle to the server. Subsequent remote procedure 
calls that use this handle are then sent directly to the bound server's port. 


The rpe_$clear_server_binding routine is used for client error recovery when a server 
dies. The port that a server uses when it restarts is not necessarily the same port that it used 
previously. Therefore, the binding that the client was using may not be correct. This routine 
enables the client to unbind from the dead server while retaining the binding to the host. 
When the client sends a request, the binding is automatically set to the server’s new port. 


Note: This routine is used by clients only. 


To clear the server binding represented in a handle, enter the following: 


rpc_S$clear_server binding(handle, &st); 


Implementation Specifics 
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rpc_$dup_handle Library Routine (NCS) 


Purpose 
Makes a copy of an RPC handle. 
Syntax 
handle_t rpc_$dup_handle (handle, status) 
handle_t handle; 
status_$t *status; 
Parameters 
Input 
handle Specifies the RPC handle to be copied. 
Output 
Status Points to the completion status. 
Description 


The rpe_$dup_handle routine returns a copy of an existing RPC handle. Both handles can 
then be used in the client program for concurrent multiple accesses to a binding. Because all 
duplicates of a handle reference the same data, a call to the rpc_$set_binding, 
rpc_$clear_binding, or rpc_$clear_server_binding routine made on any one duplicate 
affects all duplicates. However, an RPC handle is not freed until the rpc_$free_handle 
routine is called on all copies of the handle. 


Note: This routine is used by clients only. 


Return Value 
Upon successful completion, this routine returns the duplicate handle (handle_t). 


Example 
1. To create as thread_2_ handle a copy of a handle, enter the following: 
thread_2 handle = rpc_Sdup_handle(handle, &st); 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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rpc_$free_handle Library Routine (NCS) 


Purpose 
Frees an RPC handle. 

Syntax 
void rpc_$free_handle (handle, status) 
handle_t handle; 
status_$t *status; 

Parameters 
Input 
handle Specifies the RPC handle to be freed. 
Output 
Status Points to the completion status. 

Description 
The rpc_$free_handle routine frees an RPC handle by clearing the association between the 
handle and a server or an object, and then releasing the resources identified by the RPC 
handle. The client program cannot use a handle after it is freed. 
To make multiple RPC calls using the same interface but different socket addresses, replace 
the binding in an existing handle with the rpc_$set_binding routine instead of creating a 
new handle with the rpc_$free_handle and rpc_$bind routines. 
To free copies of RPC handles created by the rpc_$dup_handle routine, use the 
rpc_$free_handle routine once for each copy of the handle. However, the RPC runtime 
library does not differentiate between calling the rpc_$free_handle routine several times on 
one copy of a handle and calling it one time for each of several copies of a handle. 
Therefore, if you use duplicate handles, you must ensure that no thread inadvertently makes 
multiple rpc_$free_handle calls on a single handle. 
Note: This routine is used by clients only. 

Example 


1. To free two copies of a handle, enter the following: 


rpc_S$free_handle(handle, &st); 
rpc_$free_handle(thread_2 handle, &st); 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The rpce_$set_binding routine, rpc_$dup_handle routine. 
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rpc_$inq_binding Library Routine (NCS) 


Purpose 
Returns the socket address represented by an RPC handle. 
Syntax 
void rpc_$ing_binding (handle, sockaddr, slength, status) 
handle_t handle; 
socket_$addr_t *sockadadr, 
unsigned long *s/ength; 
status_$t *status; 
Parameters 
Input 
handle Specifies an RPC handle. 
Output 
sockaddr Points to the socket address represented by the handle parameter. 
slength Points to the length, in bytes, of the socket address (sockaddr). 
Status Points to the completion status. 
Description 
The rpc_$inq_binding routine enables a client to determine the socket address, and 
therefore the server, identified by an RPC handle. It can be used to determine which server 
is responding to a remote procedure call when a client uses an unbound handle in the call. 
Note: This routine is used by clients only. 
Diagnostics 
The rpc_$inq_binding routine fails if the following is true: 
rpc_$unbound_handle The handle is not bound and does not represent a specific 
host address. 
Example 


1. The Location Broker administrative tool, Ilb_admin, uses the following statement to 
determine the particular GLB that responded to a lookup request: 


rpc_S$ing_binding(glb S$handle, &global_broker_addr, 
&global broker _addr_len, &status); 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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rpc_$inq_object Library Routine (NCS) 


Purpose 
Returns the object UUID represented by an RPC handle. 


Syntax 
void rpc_$ing_object (handle, object_id, status) 
handle_t handle; 
uuid_$t *object_id; 
status _$t ‘status; 


Parameters 
Input 
handle Specifies an RPC handle. 
Output 


object_id Points to the UUID of the object identified by the handle parameter. 


Status Points to the completion status. 


Description 
The rpc_$inq_object routine enables a server to determine the particular object that a client 


is accessing. A server must use rpc_$inq_object if it exports an interface through which 
multiple objects may be accessed. 


A server can make this call only if the interface uses explicit handles (that is, if each 
operation in the interface has a handle argument). If the interface uses an implicit handle, 
the handle identifier is not passed to the server. 


Note: This routine is used by servers only. 
Example 
1. Adatabase server that manages multiple databases must determine the particular 


database to be accessed whenever it receives a remote procedure call. Each manager 
routine therefore makes the following call: 


rpc_S$ingq_object(handle, &db_uuid, &st); 
The routine then uses the returned UUID to identify the database to be accessed. 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


4-34 Base Operating System Reference 


rpc_$listen 


rpc_$listen Library Routine (NCS) 


Purpose 

Listens for and handles remote procedure call packets. 
Syntax 

void rpc_$listen (max_calls, status) 

unsigned long max_calls; 

status _$t *status; 
Parameters 

Input 

max_calls Specifies the maximum number of calls (in the range 1 through 10) that the 

server is allowed to process concurrently. 

Output 

Status Points to the completion status. 
Description 


The rpc_$listen routine dispatches incoming remote procedure call requests to manager 
procedures and returns the responses to the client. You must issue an rpc_$use_family or 
rpc_$use_family_wk routine before you use the rpc_$listen routine. 


If the value of the max_calls parameter is greater than 1, the server RPC runtime library 
uses Concurrent Programming Support (CPS) to handle multiple calls simultaneously. As a 
result, the manager routines must be re-entrant. This means they must maintain 
concurrency controls on any nonlocal variables to prevent conflicts among the various 
threads of execution. 


Note: This routine is used by servers only. 


Return Value 
This routine normally does not return. 


Example 
1. To have a server listen for incoming remote procedure call requests, handling up to five 
concurrently, enter the folllowing: 


rpe_$listen(5, &status); 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The rpe_$use_family routine, rpc_$use_family_wk routine. 
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rpc_$name_to_sockaddr Library Routine (NCS) 


Purpose 
Converts a host name and port number to a socket address. 
Syntax 
void rpc_$name_to_sockaddr (name, nlength, port, family, sockaddr, slength, status) 
char *name; 
unsigned long nilength; 
unsigned long port; 
unsigned long family; 
socket_$addr_t *sockaddr 
unsigned long *s/ength; 
status_$t ‘status; 
Parameters 
input 
name Points to a host name, and optionally, a port and an address family, in the 
form: family:host{porf]. The family: and [porf] parameters are optional. If 
you specify a family variable as part of the name parameter, you must 
specify socket_$unspec in the family parameter. The only supported value 
for the family variable is ip. The host parameter specifies the host name, 
and port specifies a port number in integer form. 
nlength Specifies the number of characters in the name parameter. 
port Specifies the socket port number. If you are not specifying a well-known 
port, this parameter should have the value socket_$unspec_port. The 
returned socket address will specify the Local Location Broker (LLB) 
forwarding port at the host. If you specify the port number in the name 
parameter, this parameter is ignored. 
family Specifies the address family to use for the socket address. This value 
corresponds to the communications protocol used to access the socket and 
determines how the socket address (sockaddr) is expressed. If you specify 
the address family in the name parameter, this parameter must have the 
value socket_$unspec. 
Output 
sockaddr Points to the socket address corresponding to the name, port, and family 
parameters. 
slength Points to the length, in bytes, of the socket address (specified by the 
sockaddr parameter). 
status Points to the completion status. 
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Description 
The rpc_$name_to_sockaddr routine provides the socket address for a socket, given the 
host name, the port number, and the address family. 


You can specify the socket address information either as one text string in the name 
parameter, or by passing each of the three elements as a Separate parameter. When three 
separate elements are passed, the name parameter should contain only the host name. 


Example 


1. To place in the sockaddr structure a socket address that specifies the LLB forwarding 
port at the host identified by host_name, enter the following: 


rpc_S$name_to_sockaddr(host_name, strlen(host_name), 
socket Sunspec_port,socket_ $dds, &sockaddr, &slen, &st); 


implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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rpc_$register Library Routine (NCS) 


Purpose 
Registers an interface at a server. 
Syntax 
void rpc_$register (if_spec, epv, status) 
rpc_$if_spec_t *if_spec; 
rpc_Sepv_t epv; 
status_$t *status; 
Parameters 
Input 
if_spec Points to the interface being registered. 
epv Specifies the entry point vector (EPV) for the operations in the interface. 
The EPV is normally defined in the server stub that is generated by the 
NIDL compiler from an interface definition. 
Output 
Status Points to the completion status. 
Description 
The rpe_$register routine registers an interface with the RPC runtime library. After an 
interface is registered, the RPC runtime library passes requests for that interface to the 
server. 
You can call rpe_$register multiple times with the same interface (for example, from various 
subroutines of the same server), but each call must specify the same EPV. Each registration 
increments a reference count for the registered interface. An equal number of calls to the 
rpc_Sunregister routine are then required to unregister the interface. 
Note: This routine is used by servers only. 
Diagnostics 
The rpe_$register routine fails if one or more of the following is true: 
rpc_$too_many_ifs The maximum number of interfaces is already registered with the 
server. 
rpc_$illegal_register You are trying to register an interface that is already registered, 
and you are using an EPV different from the one used when the 
interface was first registered. 
Example 
1. To register a bank interface with the bank server host’s RPC runtime library, enter the 
following: 
rpc_S$register(&bank_$if spec, bank_S$server_epv, &st); 
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Implementation Specifics 
This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The rpc_$unregister routine. 
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rpc_$set_binding Library Routine (NCS) 


Purpose 


Syntax 


Associates an RPC handle with a server. 


rpc_$set_binding (handle, sockaddr, slength, status) 
struct handle_t *handle; 

struct socket_$addr_t *sockaddr, 

int slength; 

struct status_$t *status; 


Parameters 


Input 
handle Specifies an RPC handle. 


sockaddr Specifies the socket address of the server with which the handle is being 
associated. 


slength Specifies the length, in bytes, of the socket address (sockaddr). 
Output 


status Specifies the completion status. 


Description 


Example 


The rpe_$set_binding routine sets the binding of an RPC handle to the specified server. 
The handle then identifies a specific object at a specific server. Any subsequent remote 
procedure calls that a client makes using the handle are sent to this destination. This routine 


can also replace an existing binding in a fully bound handle, or set the binding in an unbound 
handle. . 


Note: This routine is used by clients only. 


1. To set the binding on the m_handle handle to the first server in the results array, which 
was returned by a previous Location Broker lookup call, enter the following: 


rpc_$set_binding(m_handle, &lb reslts[0].saddr, 
lb_reslts[{0].saddr_len, &st); 


Implementation Specifics 
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rpc_$sockaddr_to_name Library Routine (NCS) 


Purpose : 
Converts a socket address to a host name and port number. 


Syntax 
void rpc_$sockaddr_to_name (sockaddr, slength, name, nlength, port, status) 


socket_$addr_t *sockadar, 
unsigned long s/ength; 
unsigned long *nlength; 
char *name; 

unsigned long *port; 
status _$t *status; 


Parameters 
Input 


sockaddr Points to a socket address. 


slength Specifies the length, in bytes, of socket address (sockaddr). 


Input/Output 


nlength On input, points to the length of the name parameter in the buffer. On 
Output, points to the number of characters returned in the name parameter. 


Output 


name Points to a character string that contains the host name and the address 
family in the format: family:host. The value of the family parameter must be 
ip. 


port Points to the socket port number. 


status Points to the completion status. 


Description 
The rpe_$sockaddr_to_name routine provides the address family, the host name, and the 
port number identified by the specified socket address. 


Example 
1. To take the bank server’s socket address, return the server’s host name and port, and 
then print the information, enter the following: 


rpc_S$sockaddr_to_name(&saddr, slen, name, &namelen, &port, &st); 
printf(”(bankd) name=\"%.*s\", port=%d\n"”, name, namelen, port 
3 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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rpc_$unregister Library Routine (NCS) 


Purpose 
Unregisters an interface. 
Syntax 
void rpc_$unregister (if_spec, status) 
rpc_$if_spec_t */f_spec; 
status_$t *status; 
Parameters 
Input 
if_spec Points to the interface being unregistered. 
Output 
status Points to the completion status. 
Description 
The rpce_$unregister routine unregisters an interface that the server previously registered 
with the RPC runtime library. After an interface is unregistered, the RPC runtime library does 
not pass requests for that interface to the server. | 
lf a server uses multiple calls to the rpc_$register routine to register an interface more than 
once, then the server must call the rpc_$unregister routine an equal number of times to 
unregister the interface. 
Note: This routine is used by servers only. 
Example 


1. To unregister a matrix arithmetic interface, use the following: 
rpc_Sunregister (&matrix_Sif_spec, &st); 
implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The rpc_$register routine. 
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rpc_$use_family Library Routine (NCS) 


Purpose 
Creates a socket of a specified address family for an RPC server. 

Syntax 
void rpc_$use_family (family, sockaddr, slength, status) 
unsigned long family; 
socket_$addr_t *sockaddr, 
unsigned long *s/ength; 
Status _$t *status; 

Parameters 
Input 
family Specifies the address family of the socket to be created. This value 

corresponds to the communications protocol used to access the socket and 
determines how the socket address (sockaddr) is expressed. 

Output 
sockaddr Points to the socket address of the socket on which the server listens. 
slength Points to the length, in bytes, of the socket address (sockaddr). 
status Points to the completion status. 

Description 
The rpe_$use_family routine creates a socket for a server without specifying its port 
number. (The RPC runtime software assigns the port number.) Use this routine to create the 
server socket unless the server must listen on a particular well-known port. If the socket 
must listen on a specific well-known port, use the rpc_$use_family_wk routine to create the 
socket. 
A server can listen on more than one socket. However, a server normally does not listen on 
more than one socket for each address family, regardless of the number of interfaces that it 
exports. Therefore, most servers should make this call once for each supported address 
family. 
Note: This routine is used by servers only. 

Diagnostics 


The rpe_$use_family routine can fail if one or more of the following is true: 


rpc_$cant_create_sock 
The RPC runtime library is unable to create a socket. 


rpc_$cant_bind_sock 


The RPC runtime library created a socket but is unable to bind it to a socket 
address. 


rpc_$too_many_sockets 
The server is trying to use more than the maximum number of sockets 
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allowed. The server has called the rpc_$use_family or 
rpc_$use_family_wk routines too many times. 


Example 
1. To create the bank server’s socket, enter the following: 


rpc_Suse_family(atoi(argv[1]), &saddr, &slen, &st); 


The numeric value of the address family to be used is supplied as an argument to the 
program. 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 


Related Information 
The rpc_$use_family_wk routine. 
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rpc_$use_family_wk Library Routine (NCS) 


Purpose 
Creates a socket with a well-known port for an RPC server. 


Syntax 
void rpc_$use_family_wk (family, if_spec, sockaddr, slength, status) 
unsigned long family; 
rpc_$if_spec_t *if_spec; 
socket_$addr_t *sockaddr, 
unsigned long *s/ength; 
status $t *status; 


Parameters 
Input 


family Specifies the address family of the socket to be created. This value 
corresponds to the communications protocol used to access the socket and 
determines how the socket address (sockaddr) is expressed. 


if_spec Points to the interface that will be registered by the server. Typically, this 
parameter is the $if_spec interface generated by the NIDL compiler from 
the interface definition. The well-known port is specified as an interface 
attribute. 


Output 
sockaddr Points to the socket address of the socket on which the server listens. 
slength Points to the length, in bytes, of the socket address (sockaddr). 


status Points to the completion status. 


Description 
The rpc_$use_family_wk routine creates a socket that uses the port specified with the 
if_ spec parameter. Use this routine to create a socket if a server must listen on a particular 
well-known port. Otherwise, create the socket with the rpc_$use_family routine. 


A server can listen on more than one socket. However, a Server normally does not listen on 
more than one socket for each address family, regardless of the number of interfaces that it 
exports. Therefore, most servers that use well-known ports should make this call once for 
each supported address family. 


Note: This routine is used by servers only. 


Diagnostics 
The rpc_$use_family_wk routine fails if one or more of the following is true: 


rpc_$cant_create_sock 
The RPC runtime library is unable to create a socket. 


Network Computing System (NCS) 4—45 


rpc_$use_family_wk 


rpc_$cant_bind_sock 


The RPC runtime library created 
address. 


a socket but is unable to bind it to a socket 
rpc_$too_many_sockets 


The server is trying to use more than the maximum number of sockets 
allowed. The server has called the rpc_$use_family or 


rpc_$use_family_wk routines too many times. 
rpc_$addr_in_use 


port. 


The specified address and port are already in use. This is caused by 
multiple calls to the rpc_$use_family_wk routine with the same well-known 


Example 


1. To create a well-known socket for an array processor server, use the following: 
rpc _$use_ family wk (socket_Sinternet, &matrix_S$if_spec, 
&sockaddr, slen, &st); 


Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
Related Information 


The rpc_$use_family routine. 
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uuid_$decode Library Routine (NCS) 


Purpose | 
Converts a character-string representation of a UUID into a UUID. 


Syntax 
void uuid_$decode (uuid_string, uuid, status) 
char *uu/d_string; 
uuid_$t *uuid; 
status_$t *status; 


Parameters 
input 


uuid_string Points to the character-string representation of a UUID in the form 
uuid_$string_t. 


Output 


uuid Points to the UUID that corresponds to the character string represented in 
the uuid_string parameter. 


status Points to the completion status. 
Description 


The uuid_$decode routine returns the UUID corresponding to a valid character-string 
representation of a UUID. 


Example 
1. The following call returns as my_uuid the UUID corresponding to the character-string 
representation in my_uuid_rep: 


uuid Sdecode (my_uuid_rep, &my_uuid, &status); 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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uuid_$encode Library Routine (NCS) 


Purpose 
Converts a UUID into its character-string representation. 
Syntax . 
void uuid_$encode (uuid, uuid_string) 
uuid_$t *uuid; 
char *uuid_string; 
Parameters 
Input 
uuid Points to the UUID. 
Output 
uuid_string Points to the character-string representation of a UUID, in the form 
uuid_$string t. 
Description 
The uuid_$encode call returns the character-string representation of a UUID. 
Example 


1. The following call returns as my_uuid_rep the character-string representation for the 
UUID my_uuid: 


uuid_Sencode (&my_uuid, my_uuid_ rep); 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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uuid_$gen Library Routine (NCS) 


Purpose 

Generates a new UUID. 
Syntax 

void uuid_$gen (uuid) 

uuid_$t *uuid; 
Parameters 

Output 

uuid Points to the new UUID in the form of uuid_$t. 
Description 

The uuid_$gen routine returns a new UUID. 
Example 


1. The following call returns as my_uuid anew UUID: 
uuid_ $gen (&my_uuid); 
Implementation Specifics 


This Library Routine is part of Network Computing System in Network Support Facilities in 
Base Operating System (BOS) Runtime. 
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authdes_ create Subroutine 


Purpose 
Library 


Syntax 


Enables the use of DES from the client side. 


C Library (libe.a) 


#include <rpc/rpc.h> 


AUTH * 

authdes_create (name, window, syncaddr, ckey) 
char *name; 

u_int window; 

struct sockaddr *syncadadr,; 

des_block *ckey; 


Description 


The authdes_create subroutine interfaces to the secure authentication system, known as 
Data Encryption Standard (DES). This subroutine, used from the client side, returns the 
authentication handle that allows use of the secure authentication system. 


Note: The keyserv daemon must be running for the DES authentication system to work. 


Parameters 


name Specifies the network name (or netname) of the server process owner. The 
name parameter can be either the host name derived from the 
host2netname subroutine or the user name derived from the 
user2netname subroutine. 


window Specifies the confirmation of the client credentials, given in seconds. A 
small value for the window parameter is more secure than a large one. Yet, 
choosing too small a value for the window parameter increases the 
frequency of resynchronizations due to clock drift. 


syncadar Identifies clock synchronization. If the syncaddr parameter has a NULL 
value, then the authentication system assumes that the local clock is always 
in sync with the server’s clock. The authentication system will not attempt 
resynchronizations. However, if an address is supplied, the system uses the 
address for consulting the remote time service whenever resynchronization 
is required. This parameter usually contains the address of the RPC server 
itself. 


ckey Specifies the DES key. If the value of the ckey parameter is NULL, the 
authentication system generates a random DES key to be used for the 
encryption of credentials. However, if a DES key is supplied, the supplied 
key is used. 
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Return Values 
This subroutine returns a pointer to a DES authentication object. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 
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authdes_getucred Subroutine 


Purpose 
Library 


Syntax 


Description 


Maps a DES credential into a UNIX credential. 


C Library (libe.a) 


#include <rpc/rpc.h> 


authdes_getucred (adc, uid, gid, grouplen, groups) 
struct authdes_cred “adc; 

short *uid; 

short *gid; 

short *grouplen; 

int *groups; 


The authdes_getucred subroutine interfaces to the secure authentication system known as 
Data Encryption Standard (DES). The server uses this subroutine to convert a DES 
credential, which is the independent operating system, into a UNIX credential. The 
authdes_getucred subroutine retrieves necessary information from a cache, instead of 
using the network information service (NIS). 


Note: The keyserv daemon must be running for the DES authentication system to work. 


Parameters 


adc Points to the DES credential structure. 

uid Specifies the caller’s effective user ID (UID). 
gid Specifies the caller’s effective group ID (GID). 
grouplen Specifies the group’s length. 


groups Points to the group’s array. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 


This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


The keyserv daemon. 


Network Information Service (NIS) Overview for System Management in Communication 
Concepts and Procedures. 
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auth_destroy Macro 


Purpose 
Destroys authentication information. 
Library 
C Library (libe.a) 
syntax 
#include <rpc/rpc.h> 
void 
auth_destroy (auth) 
auth *auth; 
Description 
The auth_destroy macro destroys the authentication information structure pointed to by the 
auth parameter. Destroying the structure deallocates private data structures. The use of the 
auth parameter is undefined after calling this macro. 
Parameter 


auth Points to the authentication information structure to be destroyed. 


Implementation Specifics 
This macro is part of AIX Base Operating Sisien (BOS) Runtime. 
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authnone_create Subroutine 


Purpose 

Creates NULL authentication. 
Library 

C Library (libe.a) 
Syntax 

#include <rpc/rpc.h> 

AUTH * 

authnone_create ( ) 
Description 


The authnone_create subroutine creates and returns a default Remote Procedure Call 
(RPC) authentication handle that passes NULL authentication information with each remote 
procedure call. 


Return Values 
This subroutine returns a pointer to an RPC authentication handle. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The auth_destroy macro. 


The authunix_create subroutine, authunix_create_default subroutine, svcerr_auth 
subroutine. 
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authunix_create Subroutine 


Purpose 
Creates an authentication handle with AIX permissions. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
AUTH * 
authunix_create (host, uid, gid, len, aupgids) 
char *host, 
int uid, gid 
int /en, *aupgids; 
Description 
The authunix_create subroutine creates and returns a Remote Procedure Call (RPC) 
authentication handle with AIX permissions. 
Parameters 
host Points to the name of the machine on which the permissions were created. 
uid Specifies the caller's effective user ID (UID). 
gid Specifies the caller’s effective group ID (GID). 
len Specifies the length of the groups array. 
aupgids Points to the counted array of groups to which the user belongs. 


Return Values 3 
This subroutine returns an RPC authentication handle. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The auth_destroy macro. 


The authnone_create subroutine, authunix_create_default subroutine, svcerr_auth 
subroutine. 
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authunix_create_default Subroutine 


Purpose 
Sets the authentication to default. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
AUTH * 
authunix_create_default( ) 
Description 
The authunix_create_default subroutine calls the authunix_create subroutine to create 
and return the default AIX authentication handle. 
Parameters 


This subroutine contains no parameters. 


Return Values oO 
Upon successful completion, this subroutine returns an authentication handle. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information — 
The auth_destroy macro. 


The authnone_create subroutine, authunix_create subroutine, svcerr_auth subroutine. 
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callrpc Subroutine 


Purpose 
Calls the remote procedure on the machine specified by the host parameter. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpe.h> 
callrpe (host, prognum, versnum, procnum, 
inproc, in, outproc, out) 
char *host; 
u_long prognum, versnum, procnum; 
xdrproc_t inproc; 
char * in; 
xdrproc_t oufproc; 
char *out; 
Description 
The callrpce subroutine calls a remote procedure identified by the prognum parameter, the 
versnum parameter, and the procnum parameter on the machine pointed to by the host 
parameter. 
This subroutine uses User Datagram Protocol/Internet Protocol (UDP/IP) as a transport to 
call a remote procedure. No connection will be made if the server is supported by 
Transmission Control Protocol/Internet Protocol (TCP/IP). This subroutine does not control 
time outs or authentication. 
Parameters 
host Points to the program name of the remote machine. 
prognum Specifies the number of the remote program. 
versnum Specifies the version number of the remote program. 
procnum Specifies the number of the procedure associated with the remote program 
being called. 
inproc Specifies the name of the XDR procedure that encodes the procedure 
parameters. 
in Specifies the address of the procedure arguments. 
outproc Specifies the name of the XDR procedure that decodes the procedure 
results. 
out Specifies the address where results are placed. 


Return Values 
This subroutine returns a value of enum clnt_stat. Use the clnt_perrno subroutine to 
translate this failure status into a displayed message. 
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Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related information 
The clint_call macro. 


The clnt_broadcast subroutine, clnttcp_create subroutine, clntudp_create subroutine, 
clnt_perrno subroutine, registerrpc subroutine, svc_run subroutine. 


Using the callroc Routine in Communications Programming Concepts. 


Understanding Protocols for TCP/IP, User Datagram Protocol in Communication Concepts . 
and Procedures. 
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cint_broadcast Subroutine 


Purpose 
Broadcasts a remote procedure call to all locally connected networks. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
enum cint_stat 
clnt_broadcast (prognum, versnum, procnum, 
inproc, in, outproc, out, eachresult) 
u_long prognum, versnum, procnum; 
xdrproc_t inproc; 
char *in; 
xdrproc_t oufproc; 
char *out; 
resultproc_t eachresult; 
Description 
The cint_broadcast subroutine broadcasts a remote procedure call to all locally connected 
networks. The remote procedure is identified by the prognum, versnum, and procnum 
parameters on the workstation identified by the host parameter. 
Broadcast sockets are limited in size to the maximum transfer unit of the data link. For 
Ethernet, this value is 1500 bytes. . 
When a Client broadcasts a remote procedure call over the network, a number of server 
processes respond. Each time the client receives a response, the cint_broadcast 
subroutine calls the eachresult routine. The eachresult routine takes the following form: 
eachresult (out, *addr 
char *out; 
struct sockaddr_in *adar,; 
Parameters 
prognum Specifies the number of the remote program. 
versnum Specifies the version number of the remote program. 
procnum Identifies the procedure to be called. 
inproc Specifies the procedure that encodes the procedure’s parameters. 
in Specifies the address of the procedure’s arguments. 
outproc Specifies the procedure that decodes the procedure results. 
out Specifies the address where results are placed. 
eachresult Specifies the procedure to call when clients respond. 
addr Specifies the address of the workstation that sent the results. 
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clnt_broadcast 


Return Values 
If the eachresult subroutine returns a value of 0, the clnt_broadcast subroutine waits for 
more replies. Otherwise, the clnt_broadcast subroutine returns with the appropriate results. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The callrpe subroutine. 


Sockets Overview in Communications Programming Concepts. 
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clnt_call Macro 


Purpose 


Library 


Syntax 


Calls the remote procedure associated with the c/nt parameter. 


C Library (libce.a) 


#include <rpc/rpc.h> 
enum cint_stat 


cint_call (cint, procnum, inproc, in, outproc, out, tout) 
CLIENT *cint; 

u_long procnum; 

xdrproc_t inproc; 

char *in; 

xdrproc_t outoroc; 

char *out; 

struct timeval tout; 


Description 


The clint_call macro calls the remote procedure associated with the client handle pointed to 
by the c/nt parameter. 


Parameters 


cint Points to the structure of the client handle that results from a Remote 
Procedure Call (RPC) client creation subroutine, such as the 
cIntudp_create subroutine that opens a User Datagram Protocol/Internet 
Protocol (UDP/IP) socket. 


procnum Identifies the remote procedure on the host machine. 

inproc Specifies the procedure that encodes the procedure’s parameters. 
in Specifies the address of the procedure’s arguments. 

outproc Specifies the procedure that decodes the procedure’s results. 

out Specifies the address where results are placed. 

tout Sets the time allowed for results to return. 


Implementation Specifics 
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This macro is part of AIX Base Operating System (BOS) Runtime. 
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cint_call 


Related Information 
The callrpe subroutine, clnt_perror subroutine, cilnttcp_create subroutine, clntudp_create 
subroutine. 


Sockets Overview in Communications Programming Concepts. 


User Datagram Protocol (UDP) in Communication Concepts and Procedures. 
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clnt_control Macro 


Purpose 
Changes or retrieves various information about a client object. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
bool_t 
cint_control (c/, req, info) 
CLIENT “ci; 
int req 
char “info; 
Description 
The cint_control macro is used to change or retrieve various information about a client 
object. 
User Datagram Protocol (UDP) and Transmission Control Protocol (TCP) have the following 
supported values for the req parameter’s argument types and functions: 
Values for the req Parameter Argument Type Function 
CLSET_TIMEOUT struct timeval Sets total time out 
CLGET_TIMEOUT struct timeval Gets total time out 
Note: If the time out is set using the clnt_control subroutine, the timeout parameter 
passed to the clnt_call subroutine will be ignored in all future calls. 
CLGET_SERVER_ADDR struct sockaddr Gets server’s address 
The following operations are valid for UDP only: 
CLSET_RETRY_TIMEOUT struct timeval Sets the retry time out 
CLGET_RETRY_TIMEOUT struct timeval Gets the retry time out 
Note: The retry time out is the time that User Datagram Protocol/Remote Procedure Call 
(UDP/RPC) waits for the server to reply before retransmitting the request. 
Parameters 
cl Points to the structure of the client handle. 
req Indicates the type of operation. 
info Points to the information for request type. 


Return Values 
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Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 
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cint_control 


Implementation Specifics 
This macro is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The clnt_call macro. 
The clnttcp_create subroutine, clntudp_create subroutine. 


Understanding Protocols for TCP/IP, User Datagram Protocol (UDP) in Communication 
Concepts and Procedures. 
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clnt_create Subroutine 


Purpose 
Creates and returns a generic client handle. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
CLIENT * 
clnt_create (host, prognum, versnum, protocol 
char *host; 


unsigned prognum, versnum; 
char *protocol; 


Description 
Creates and returns a generic client handle. 


RPC messages transported by UDP/IP can hold up to 8K bytes of encoded data. Use this 
transport for procedures that take arguments or return results of less than 8K bytes. 


Parameters 
host Identifies the name of the remote host where the server is located. 
prognum Specifies the program number of the remote program. 
versnum Specifies the version number of the remote program. 
protocol Identifies which data transport protocol the program is using (UDP or TCP). 


Return Values 
Upon successful completion, this subroutine returns a client handle. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The clnt_control macro, clnt_destroy macro. 
The clnttcp_create subroutine, clntudp_create subroutine. 


Understanding Protocols for TCP/IP, User Datagram Protocol (UDP) in Communication 
Concepts and Procedures. 
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clnt_destroy Macro 


Purpose 
Destroys the client's RPC handle. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
void 
cint_destroy (c/nf) 
CLIENT ‘clint; 
Description 
The clnt_destroy macro destroys the client's Remote Procedure Call (RPC) handle. 
Destroying the client's RPC handle deallocates private data structures, including the cint 
parameter itself. The use of the c/nt parameter becomes undefined upon calling the 
cint_destroy macro. 
Parameter 


cint Points to the structure of the client handle. 


Implementation Specifics 
This macro is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The cintudp_create subroutine, cint_create subroutine. 


Sockets Overview in Communications Programming Concepts. 
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clnt_freeres Macro 


Purpose 
Frees data that was allocated by the RPC/XDR system. 


Library 
C Library (libe.a) 


Syntax 
#include <rpc/rpc.h> 
cint_freeres (c/nt, outproc, out) 
CLIENT *c/nt; 


xdrpoc_t outoroc; 
char *out; 


Description 
The cint_freeres macro frees data allocated by the Remote Procedure Call/eXternal Data 
Representation (RPC/XDR) system. This data was allocated when the RPC/XDR system 
decoded the results of an RPC call. 


Parameters 
clint Points to the structure of the client handle. 


outproc Specifies the XDR subroutine that describes the results in simple decoding 
primitives. 


out Specifies the address where the results are placed. 


Implementation Specifics 
This macro is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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cint_geterr Macro 


Purpose 
Copies error information from a client handle. 


Library 
C Library (libe.a) 


Syntax 
#include <rpc/rpc.h> 
void 
cint_geterr (clint, errp) 


CLIENT *cint; 
struct rpc_err *errp; 


Description 
The clnt_geterr macro copies error information from a client handle to an error structure. 


Parameters 
cint Points to the structure of the client handle. 


errp Specifies the address of the error structure. 


Implementation Specifics 
This macro is part of AIX Base Operating System (BOS) Runtime. 
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clnt_pcreateerror Subroutine 


Purpose 
Library 


Syntax 


Indicates why a client RPC handle was not created. 


C Library (libe.a) 


#include <rpc/rpc.h> 


void 
clnt_pcreateerror (s) 
char *s; 


Description 


The clnt_pcreateerror subroutine writes a message to standard error output, indicating why 
a client Remote Procedure Call (RPC) handie could not be created. The message is 
preceded by the string pointed to by the s parameter and a colon. 


Use this subroutine if one of the following calls fails: the cintraw_create subroutine, 
clnttcp_create subroutine, or clntudp_create subroutine. 


Parameters 


Ss Points to a character string that represents the error text. 


Implementation Specifics 


This subroutine is part of AIX Base Operating System (BOS) Runtime. 


_ Related Information 
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The clnt_create subroutine, clntraw_create subroutine, clnttcp_create subroutine, 
clntudp_create subroutine, clnt_spcreateerror subroutine. 
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clnt_perrno Subroutine 


Purpose 
Specifies the condition of the stat parameter. 


Library 
C Library (libe.a) 


Syntax 
#include <rpc/rpc.h> 
void 
clnt_perrno (staf) 
enum clint_stat staf; 


Description 
The cint_perrno subroutine writes a message to standard error output, corresponding to the 
condition specified by the stat parameter. 


This subroutine is used after a callrpe subroutine fails. The cint_perrno subroutine 
translates the failure status (the enum cint_stat subroutine) into a message. 


If the program does not have a standard error output, or the programmer does not want the 
message to be output with the printf subroutine, or the message format used is different 
from that supported by the clnt_perrno subroutine, then the clnt_sperrno subroutine is 
used instead of the clnt_perrno subroutine. 


Parameters 
Stat Specifies the client error status of the remote procedure call. 


Return Values 


The clnt_perrno subroutine translates and displays the following enum cint_stat error 
status codes: 


RPC_SUCCESS =0 Call succeeded. 
RPC_CANTENCODEARGS = 1 Cannot decode arguments. 
RPC_CANTDECODERES = 2 Cannot decode results. 
RPC_CANTSEND = 3 Failure in sending call. 
RPC_CANTRECV = 4 Failure in receiving result. 
RPC_TIMEDOUT = 5 Call timed out. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (B08) Runtime. 


Related Information 
The calirpce subroutine, clnt_sperrno subroutine. 
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clnt_perror Subroutine 


Purpose 
Indicates why a remote procedure call failed. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
cint_perror (cint, s) 
CLIENT *cint; 
char *s; 
Description ’ 
The cint_perror subroutine writes a message to standard error output indicating why a 
remote procedure call failed. The message is prepended with the string pointed to by the s 
parameter and a colon. 
This subroutine is used after the clnt_call macro. 
Parameters 
clint Points to the structure of the client handle. 
s Points to a character string that represents the error text. 


Return Values 
This subroutine returns an error string to standard error output. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The clint_call macro. 


The clnt_sperror subroutine. 
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cint_spcreateerror Subroutine 


Purpose 
Indicates why a client RPC handle was not created. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
char * 
clnt_spcreateerror (s) 
char *s; 
Description 
The cint_spcreateerror subroutine returns a string indicating why a client Remote 
Procedure Call (RPC) handle was not created. 
Note: This subroutine returns the pointer to static data that is overwritten on each call. 
Parameters 


s Points to a character string that represents the error text. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The clnt_pcreateerror subroutine. 
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clnt_sperrno Subroutine 


Purpose 
Specifies the condition of the stat parameter by returning a pointer to a string containing a 
status message. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
char * 
cInt_sperrno (staf) 
enum cint_stat staf; 
Description 
The clnt_sperrno subroutine specifies the condition of the stat parameter by returning a 
pointer to a string containing a status message. The string ends with a new-line character. 
Whenever one of the following conditions exists, the clnt_sperrno subroutine is used 
instead of the clnt_perrno subroutine when a callrpe routine fails: 
e The program does not have a standard error output. This is common for programs 
running as servers. 
e The programmer does not want the message to be output with the printf subroutine. 
e A message format differing from that supported by the clInt_perrno subroutine is being 
used. 
Note: The cint_sperrno subroutine does not return the pointer to static data, so the result 
is not overwritten on each call. 
Parameters 


Stat Specifies the client error status of the remote procedure call. 


Return Values 
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The clnt_sperrno subroutine translates and displays the following enum cint_stat error 
status messages: 


RPC_SUCCESS =0 Call succeeded. 
RPC_CANTENCODEARGS = 1 Cannot decode arguments. 
RPC_CANTDECODERES = 2 Cannot decode results. 
RPC_CANTSEND = 3 Failure in sending call. 
RPC_CANTRECV = 4 Failure in receiving result. 
RPC_TIMEDOUT = 5 Call timed out. 
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Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The cint_perrno subroutine. 
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clnt_sperror Subroutine 


Purpose 
Indicates why a remote procedure call failed. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpc.h> 


char * 
clnt_sperror (c/,s) 
CLIENT *c/; 

char *s; 


Description 
The clnt_sperror subroutine returns a string to standard error output indicating why a 


Remote Procedure Call (RPC) call failed. This subroutine also returns the pointer to static 
data overwritten on each call. 


Parameters 
cl Points to the structure of the client handle. 


Ss Points to a character string that represents the error text. 


Return Values 
This subroutine returns an error string to standard error output. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The clnt_perror subroutine. 
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cintraw_create Subroutine 


Purpose 
Creates a toy RPC client for simulation. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
CLIENT * 
cintraw_create (prognum, versnum) 
u_long prognum, versnum; 
Description 
The clntraw_create subroutine creates a toy Remote Procedure Call (RPC) client for 
simulation of a remote program. This toy client uses a buffer located within the address 
space of the process for the transport to pass messages to the service. If the corresponding 
RPC server lives in the same address space, simulation of RPC and acquisition of RPC 
overheads, such as round-trip times, are done without kernel interference. 
Parameters 
prognum Specifies the program number of the remote program. 
versnum Specifies the version number of the remote program. 


Return Values 


Upon successful completion, this subroutine returns a pointer to a valid RPC client. If 
unsuccessful, it returns a value of NULL. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The clnt_pcreateerror subroutine, svcraw_create subroutine. 
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cilnttcp_create Subroutine 


Purpose 
Creates a TCP/IP client transport handle. 
Library 
C Library (libe.a) 
Syntax 
CLIENT * 
cinttcp_create (addr, prognum, versnum, sockp, sendsz, recvsz) 
struct sockaddr_in *adar, 
u_long prognum, versnum; 
int *sockp; 
u_int sendsz, recvsz; 
Description 
The cinttcp_create subroutine creates a Remote Procedure Call (RPC) client transport 
handle for a remote program. This client uses Transmission Control Protocol/Internet 
Protocol (TCP/IP) as the transport to pass messages to the service. 
The TCP/IP remote procedure calls use buffered input/output (I/O). Users can set the size of 
the send and receive buffers with the sendsz and recvsz parameters. If the size of either 
buffer is set to a value of 0, the svctcp_create subroutine picks suitable default values. 
Parameters 


addr Points to the Internet address of the remote program. If the port number for 
this Internet address (addr—>sin_port) is a value of 0, then the addr 
parameter is set to the actual port on which the remote program is listening. 
The client making the remote procedure call consults the remote portmap 
daemon to obtain the port information. 


prognum Specifies the program number of the remote program. 
versnum Specifies the version number of the remote program. 
sockp Specifies a pointer to a socket. If the value of the sockp parameter is 


RPC_ANYSOCK, the cinttcp_create subroutine opens a new socket and 
sets the sockp pointer to the new socket. — 


sendsz Sets the size of the send buffer. 


reCvsz Sets the size of the receive buffer. 


Return Values 


Upon successful completion, this routine returns a valid TCP/IP client handle. If 
unsuccessful, it returns a value of NULL. 


Implementation Specifics 
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This subroutine is part of AIX Base Operating System (BOS) Runtime. 
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Related Information 
The portmap daemon. 


The clnt_call macro. 


The calirpe subroutine, clntudp_create subroutine, svctcp_create subroutine, 
clnt_pcreateerror subroutine. 


Sockets Overview in Communications Programming Concepts. 


Understanding Protocols for TCP/IP in Communication Concepts and Procedures. 
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cIntudp_create Subroutine 


Purpose 
Creates a UDP/IP client transport handle. 
Library 
C Library (libc.a) 
Syntax 
#include <rpc/rpc.h> 
CLIENT * 
clntudp_create (addr, prognum, versnum, wait, sockp ) 
struct sockaddr_in *adar, 
u_long prognum, versnum; 
struct timeval wait; 
int *sockp; 
Description 
The clntudp_create subroutine creates a Remote Procedure Call (RPC) client transport 
handle for a remote program. The client uses User Datagram Protocol/Internet Protocol 
(UDP/IP) as the transport to pass messages to the service. 
RPC messages transported by UDP/IP can hold up to 8K bytes of encoded data. Use this 
subroutine for procedures that take arguments or return results of less than 8K bytes. 
Parameters 


adar Points to the Internet address of the remote program. If the port number for 
this Internet address (addr—>sin_port) is 0, then the value of the addr 
parameter is set to the port that the remote program is listening on. The 
clntudp_create subroutine consults the remote portmap daemon for this 


information. 
prognum Specifies the program number of the remote program. 
versnum Specifies the version number of the remote program. 
wait Sets the amount of time that the UDP/IP transport waits to receive a 


response before the transport sends another remote procedure call or the 
remote procedure call times out. The total time for the call to time out is set 
by the cint_call macro. 


sockp Specifies a pointer to a socket. If the value of the sockp parameter is 


RPC_ANYSOCK, the clntudp_create subroutine opens a new socket and 
sets the sockp pointer to that new socket. 


Return Values 


Upon successful completion, this subroutine returns a valid UDP client handle. If 
unsuccessful, it returns a value of NULL. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 
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Related Information 
The portmap daemon. 


The clint_call macro. 


The calirpe subroutine, clnt_pcreateerror subroutine, clnttcp_create subroutine, 
svcudp_create subroutine. 


Sockets Overview in Communications Programming Concepts. 


User Datagram Protocol (UDP) in Communication Concepts and Procedures. 
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dbm_close Subroutine 


Purpose 

Closes a database. 
Library 

C Library (libe.a) 
Syntax 

#include <ndbm.h> 

void dbm_close (ab) 

DBM *ab; 
Description 

The dbm_close subroutine closes a database. 
Parameter 


db Specifies the database to close. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The dbmclose subroutine. 
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dbm_delete Subroutine 


Purpose 

Deletes a key and its associated contents. 
Library 

C Library (libe.a) 
Syntax 

#include <ndbm.h> 

int dbm_delete (db, key) 

DBM *db; 

datum key; 
Description 

The dbm_delete subroutine deletes a key and its associated contents. 
Parameters | 

db Specifies a database. 

key Specifies the key to delete. 


Return Values 
Upon successful completion, this subroutine returns a value of 0 (zero). If unsuccessful, it 
returns a negative value. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The delete subroutine. 
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dbm_fetch Subroutine 


Purpose 
Accesses data stored under a key. 
Library 
C Library (libe.a) 
Syntax 
#include <ndbm.h> 
datum dbm_fetch(db, key) 
DBM *ab; 
datum key; 
Description 
The dbm_fetch subroutine accesses data stored under a key. 
Parameters 
db Specifies the database to access. 
key Specifies the input key. 


Return Values 
Upon successful completion, this subroutine returns a datum structure containing the value 


returned for the specified key. If it is unsuccessful, the dptr field of the datum structure is set 
to NULL. 


Implementation Specifics 
~ This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The fetch subroutine. 
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dbm_firstkey Subroutine 


Purpose 

Returns the first key in a database. 
Library 

C Library (libe.a) 
Syntax 

#include <ndbm.h> 

datum dbm_firstkey (db) 

DBM *ab; 
Description 

The dbm_firstkey subroutine returns the first key in a database. 
Parameter 


db Specifies the database to access. 


Return Values | 
Upon successful completion, this subroutine returns a datum structure containing the value 
for the first key. If it is unsuccessful, the dptr field of the datum structure is set to NULL. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The firstkey subroutine. 
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dbm_nextkey Subroutine 


Purpose 

Returns the next key in a database. 
Library 

C Library (libe.a) 
Syntax 

#include <ndbm.h> 

datum dbm_nextkey (db) 

DBM *ab; 
Description 

The dbm_nextkey subroutine returns the next key in a database. 
Parameter 


db Specifies the database to access. 


Return Values 
Upon successful completion, this subroutine returns a datum structure containing the value 
for the next key. If it is unsuccessful, the dptr field of the datum structure is set to NULL. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The nextkey subroutine. 
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dbm_open Subroutine 


Purpose 
Opens a database for access. 


Library 
C Library (libe.a) 


Syntax 
#include <ndbm.h> 
DBM *dbm_open (file, flags, mode) 
char *file; 
int flags, mode; 


Description 
The dbm_open subroutine opens a database for access. This opens and/or creates the 


file.dir and file.pag files, depending on the flags parameter. The returned DBM structure is 
used as input to other NDBM routines. 


Parameters 
file Specifies the path to open a database. 


flags Specifies the flags required to open a subroutine. 


mode Specifies the mode required to open a subroutine. 


Return Values 
Upon successful completion, this subroutine returns a pointer to the DBM structure. If 
unsuccessful, it returns a value of NULL. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The dbminit subroutine. 
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dbm_ store Subroutine 


Purpose 
Places data under a key. 
Library 
C Library (libc.a) 
Syntax 
#include <ndbm.h> 
int dbm_store (db, key, content, flags) 
DBM *ab; 
datum key, content; 
int flags; 
Description 
The dbm_store subroutine places data under a key. 
‘Parameters 
db Specifies the database to store. 
key Specifies the input key. 
content Specifies the value associated with the key to store. 
flags Contains either DBM_INSERT or DBM_REPLACE. If the dbm_store 


subroutine is called with flags set to DBM_INSERT, and if an entry for the 
key already exists, then the dbm_store subroutine returns a value of 1. If 
the flags parameter is set to DBM_REPLACE then the entry will be replaced 
if it already exists. 


Return Values 


Upon successful completion, this subroutine returns a value of 0 (zero). If unsuccessful, it 
returns a negative value. If the dbm_store subroutine is called with the flags parameter set 
to DBM_INSERT and an existing entry is found, then it returns a value of 1. 


Implementation Specifics 
This subroutine is part of AIX Base peraiing System (BOS) Runtime. 


Related Information 
The store subroutine. 
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dbmclose Subroutine 


Purpose 

Closes a database. 
Library 

DBM Library (libdbm.a) 
Syntax 

#include <dbm.h> 

void dbmclose (db) 

DBM “ab; 
Description 

The dbmclose subroutine closes a database. 
Parameter 


db Specifies the database to close. 


implementation Specifics 


This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The dbm_close subroutine. 
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dbminit Subroutine 


Purpose 
Opens a database for access. 
Library 
DBM Library (libdbm.a) 
Syntax 
#include <dbm.h> 
dbminit (file) 
char *file; 
Description 
The dbminit subroutine opens a database for access. At the time of the call, the file.dir and 
file.pag files must exist. 
Note: To build an empty database, create zero-length .dir and .pag files. 
Parameter 


file Specifies the path name of the database to open. 


Return Values 
Upon successful completion, this subroutine returns a value of 0 (zero). If unsuccessful, it 
returns a negative value. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The dbm_open subroutine. 
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delete Subroutine 


Purpose 

Deletes a key and its associated contents. 
Library 

DBM Library (libdbm.a) 
Syntax 

#include <dbm.h> 

delete (key) 

datum key; 
Description 

The delete subroutine deletes a key and its associated contents. 
Parameter 


key Specifies the key to delete. 


Return Values 
Upon successful completion, this subroutine returns a value of 0 (zero). If unsuccessful, it 
returns a negative value. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The dbm_delete subroutine. 
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fetch Subroutine 


Purpose 

Accesses data stored under a key. 
Library 

DBM Library (libdbm.a) 
Syntax 

#include <dbm.h> 

datum fetch (key) 

datum key; 
Description 

The fetch subroutine accesses data stored under a key. 
Parameter 


key Specifies the input key. 


Return Values 


Upon successful completion, this subroutine returns data corresponding to the specified key. 
If it is unsuccessful, a NULL value is indicated in the dptr field of the datum structure. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The dbm_fetch subroutine. 
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firstkey Subroutine 


Purpose 
Returns the first key in the database. 
Library 
DBM Library (libdbm.a) 
Syntax 
#include <dbm.h> 
datum firstkey () 
Description 
The firstkey subroutine returns the first key in the database. 
Parameters 


This subroutine contains no parameters. 


Return Values 
Returns a datum structure containing the first key value pair. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The dbm_firstkey subroutine. 
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get_myaddress Subroutine 


Purpose 
Gets the user’s IP address. 
Library 
C Library (libc.a) 
Syntax 
#include <rpc/rpc.h> 
void 
get_myaddress (addr) 
struct sockaddr_in *adar, 
Description 
The get_myaddress subroutine gets the machine’s Internet Protocol (IP) address without 
consulting the library routines that access the /etc/hosts file. 
Parameter 


addr Specifies the address where the machine's IP address is placed. The port 
number is set to a value of htons (PMAPPORT). 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The /etc/hosts file. 


Internet Protocol (IP) Overview in Communication Concepts and Procedures. 
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getnetname Subroutine 


Purpose 
Installs the network name of the caller in the array specified by the name parameter. 
Library 
C Library (libc.a) 
Syntax 
#include <rpc/rpc.h> 
getnetname (name) 
char name [MAXNETNAMELEN]; 
Description 
The getnetname subroutine installs the caller’s unique, operating-system-independent 
network name in the fixed-length array specified by the name parameter. 
Parameter 


name Specifies the network name (or netname) of the server process owner. The 
name parameter can be either the host name derived from the 
host2netname subroutine or the user name derived from the 
user2netname subroutine. 


Return Values 
Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The host2netname subroutine, user2netname subroutine. 
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host2netname Subroutine 


Purpose 
Converts a domain-specific host name to an operating-system-independent network name. 
Library 
C Library (libce.a) 
Syntax 
#include <rpc/rpc.h> 
host2netname (name, host, domain) 
char *name; 
char *host 
char *domain 
Description 
The host2netname subroutine converts a domain-specific host name to an 
operating-system-independent network name. 
This subroutine is the inverse of the netname2host subroutine. 
Parameters 


name Points to the network name (or netname) of the server process owner. The 
name parameter can be either the host name derived from the 
host2netname subroutine or the user name derived from the 
user2netname subroutine. 


host Points to the name of the machine on which the permissions were created. 


domain Points to the domain name. 


Return Values 
Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The netname2host subroutine, user2netname subroutine. 
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key_decryptsession Subroutine 


Purpose 
Decrypts a server network name and a DES key. 

Library 
C Library (libe.a) 

Syntax 
key_decryptsession (remotename, deskey) 
char *remotename; 
des_block *deskey; 

Description 
The key_decryptsession subroutine interfaces to the keyserv daemon, which is associated 
with the secure authentication system known as Data Encryption Standard (DES). The 
subroutine takes a server network name and a DES key and decrypts the DES key by using 
the public key of the server and the secret key associated with the effective user number 
(UID) of the calling process. User programs rarely need to call this subroutine. System 
commands such as keylogin and the Remote Procedure Call (RPC) library are the main 
clients. 
This subroutine is the inverse of the key_encryptsession subroutine. 

Parameters 


remotename Points to the remote host name. 
deskey Points to the des_block structure. 
Return Values 


Upon successful completion, this subroutine returns a value of 0. If unsuccessful, it returns a 
value of -1. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The keylogin command. 


The keyserv daemon. 


The key_encryptsession subroutine. 
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key_encryptsession Subroutine 


Purpose 
Encrypts a server network name and a DES key. 

Library 
C Library (libe.a) 

Syntax 
#include <rpc/rpc.h> 
key_encryptsession (remotename, deskey) 
char *remotename; 
des_block *deskey; 

Description 
The key_encryptsession subroutine interfaces to the keyserv daemon, which is associated . 
with the secure authentication system know as Data Encryption Standard (DES). This 
subroutine encrypts a server network name and a DES key. To do so, the routine uses the 
public key of the server and the secret key associated with the effective user number (UID) 
of the calling process. System commands such as keylogin and the Remote Procedure Call 
(RPC) library are the main clients. User programs rarely need to call this subroutine. 
This subroutine is the inverse of the key_decryptsession subroutine. 

Parameters 


remotename _ Points to the remote host name. 
deskey Points to the des_ block structure. 


Return Values 


Upon successful completion, this subroutine returns a value of 0. If unsuccessful, it returns a 
value of —1. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The keylogin command. 
The keyserv daemon. 


The key_decryptsession subroutine. 
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key_gendes Subroutine 


Purpose 
Asks the keyserv daemon for a secure conversation key. 

Library 
C Library (libe.a) 

Syntax 
#include <rpc/rpc.h> 
key_gendes (deskey) 
des_block *deskey; 

Description 
The key_gendes subroutine interfaces to the keyserv daemon, which is associated with the 
secure authentication system know as Data Encryption Standard (DES). This subroutine 
asks the keyserv daemon for a secure conversation key. Choosing a key at random is not 
recommended because the common ways of choosing random numbers, such as the 
Current time, are easy to guess. User programs rarely need to call this subroutine. System 
commands such as keylogin and the Remote Procedure Call (RPC) library are the main 
Clients. 

Parameters 
deskey Points to the des_block structure. 


Return Values 
Upon successful completion, this subroutine returns a value of 0. If unsuccessful, it returns a 
value of —1. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The keylogin command. 


The keyserv daemon. 
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key_setsecret Subroutine 


Purpose 
Sets the key for the effective UID of the calling process. 

Library 
C Library (libe.a) 

Syntax 
#include <rpc/rpc.h> 
key_setsecret (key) 
char *key; 

Description 
The key_setsecret subroutine interfaces to the keyserv daemon, which is associated with 
the secure authentication system know as Data Encryption Standard (DES). This subroutine 
is used to set the key for the effective user number (UID) of the calling process. User 
programs rarely need to call this subroutine. System commands such as keylogin and the 
Remote Procedure Call (RPC) library are the main clients. 

Parameters 


key Points to the key name. 


Return Values 


Upon successful completion, this subroutine returns a value of 0. If unsuccessful, it returns a 
value of —1. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The keylogin command. 


The keyserv daemon. 
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netname2host Subroutine 


Purpose 
Converts an operating-system-independent network name to a domain-specific host name. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpc.h> 


netname2host (name, host, hostlen) 
char *name; 

char *host; 

int hostlen; 


Description 
The netname2host subroutine converts an operating-system-independent network name to 
a domain-specific host name. 


This subroutine is the inverse of the host2netname subroutine. 


Parameters 


name Specifies the network name (or netname) of the server process owner. The 
name parameter can be either the host name derived from the 
host2netname subroutine or the user name derived from the 
user2netname subroutine. 


host Points to the name of the machine on which the permissions were created. 


hostlen Specifies the size of the host name. 


Return Values 
Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The host2netname subroutine, user2netname subroutine. 
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netname2user Subroutine 


Purpose 
Converts from an operating-system-independent network name to a domain-specific UID. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpc.h> 


netname2user (name, uidp, gidp, gidlenp, gidlist) 
char *name; 
int *u/dp; 
int *gidp; 
int *gidlenp; 
int *gidlist, 
Description 
The netname2user subroutine converts from an operating-system-independent network 


name to a domain-specific user number (UID). This subroutine is the inverse of the 
user2netname subroutine. 


Parameters 


name Points to the network name (or netname) of the server process owner. The 
name parameter can be either the host name derived from the 
host2netname subroutine or the user name derived from the 
user2netname subroutine. 


uidp Points to the user ID. 

gidp Points to the group ID. 

gidlenp Points to the size of the group ID. 
gidlist Points to the group list. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The host2netname subroutine, user2netname subroutine. 


5-54 Base Operating System Reference 


nextkey 


nextkey Subroutine 


Purpose 

Returns the next key in a database. 
Library 

DBM Library (libdbm.a) 
Syntax 

#include <dbm.h> 

datum nextkey (key) 

datum key; 
Description 

The nextkey subroutine returns the next key in a database. 
Parameters 


key Specifies the input key. This value has no effect on the return value but 
must be present. 


Return Values 
Returns a datum structure containing the next key-value pair. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The dbm_nextkey subroutine. 
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pmap_getmaps Subroutine 


Purpose 
Returns a list of the current RPC program to port mappings on the host. 


Library 
C Library (libc.a) 


Syntax 


#include <rpc/rpc.h> 


struct pmaplist * 
pmap_getmaps (adar) 
struct sockaddr_in *adar; 


Description 
The pmap_getmaps subroutine acts as a user interface to the portmap daemon. The 
subroutine returns a list of the current Remote Procedure Call (RPC) program to port 


mappings on the host located at the Internet Protocol (IP) address pointed to by the addr 
parameter. 


Note: The rpcinfo —p command calls this subroutine. 


Parameter 
adar Specifies the address where the machine’s IP address is placed. 


Return Value 
If there is no list of current RPC programs, this procedure returns a value of NULL. — 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The rpcinfo command. 


The portmap daemon. 


The pmap_set subroutine, pmap_unset subroutine, svc_register subroutine. 
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pmap_getport Subroutine 


Requests the port number on which a service waits. 


C Library (libce.a) 


#include <rpc/rpc.h> 


pmap_getport (addr, prognum, versnum, protocol) 
struct sockaddr_in *addr 
u_long prognum, versnum, protocol; 


The pmap_getport subroutine acts as a user interface to the portmap daemon in order to 
return the port number on which a service waits. 


Purpose 
Library 
Syntax 
u_short 
Description 
Parameters 
addr 
prognum 
versnum 
protocol 


Return Values 


Points to the Internet Protocol (IP) address of the host where the remote 
program that supports the waiting service resides. 


Specifies the program number of the remote program. 
Specifies the version number of the remote program. 


Specifies the transport protocol that the service recognizes. 


If the mapping does not exist or the Remote Procedure Call (RPC) system could not contact 
the remote portmap daemon, this subroutine returns a value of 0. If the remote portmap 
daemon could not be contacted, the rpc_createerr subroutine contains the RPC status. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


The portmap daemon. 


Internet Protocol (IP) in Communication Concepts and Procedures. 
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pmap_rmtcall Subroutine 


Purpose 
Instructs the portmap daemon to make a remote procedure call. 
Library 
C Library (libce.a) 
Syntax 
#include <rpc/rpc.h> 
enum cint_stat 
pmap_rmtcall (addr, prognum, versnum, procnum, 
inproc, in, outproc, out, tout, portp) 
struct sockaddr_in *adar, 
u_long prognum, versnum, procnum; 
xdrproc_t inproc; 
char *in; 
xdrproc_t outproc; 
char *out; 
struct timeval tout; 
u_long *portp; 
Description 
The pmap_rmtcall subroutine is a user interface to the portmap daemon. The routine 
instructs the host portmap daemon to make a remote procedure call. Clients consult the 
portmap daemon when sending out Remote Procedure Call (RPC) calls for given program 
numbers. The portmap daemon tells the client the ports to which to send the calls. 
Parameters 
adar Points to the Internet Protocol (IP) address of the host where the remote 
program that supports the waiting service resides. 
prognum Specifies the program number of the remote program. 
versnum Specifies the version number of the remote program. 
procnum Identifies the procedure to be called. 
inproc Specifies the eXternal Data Representation (XDR) routine that encodes the 
remote procedure parameters. 
in Points to the address of the procedure arguments. 
outproc Specifies the XDR routine that decodes the remote procedure results. 
out Points to the address where the results are placed. 
tout Sets the time the routine waits for the results to return before sending the 
call again. , 
portp Points to the program port number if the procedure succeeds. 
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pmap_rmtcall 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The portmap daemon. 


The clnt_broadcast subroutine. 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 


Internet Protocol (IP) in Communication Concepts and Procedures. 
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pmap_set Subroutine 


Maps a remote procedure call to a port. 


#include <rpc/rpc.h> 


pmap_set (prognum, versnum, protocol, port) 
u_long prognum, versnum, protocol; 


The pmap_set subroutine acts as a user interface to the portmap daemon to map the 


program number, version number, and protocol of a remote procedure call to a port on the 
machine portmap daemon. 


Note: The pmap_set subroutine is called by the svc_register subroutine. 


Specifies the program number of the remote program. 
Specifies the version number of the remote program. 


Specifies the transport protocol that the service recognizes. The values for 
this parameter can be IPPROTO_UDP or IPPROTO_TCP. 


Purpose 
Library 
C Library (libe.a) 
Syntax 
u_short port; 
Description 
Parameters 
prognum 
versnum 
protocol 
port 


Return Values 


Specifies the port on the machine’s portmap daemon. 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 


value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


The portmap daemon. 


The pmap_getmaps subroutine, pmap_unset subroutine, svc_register subroutine. 


Understanding Protocols for TCP/IP in Communication Concepts and Procedures. 
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pmap_unset Subroutine 


Purpose 
Destroys the mappings between a remote procedure call and the port. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
pmap_unset (prognum, versnum) 
u_long prognum, versnum; 
Description 
The pmap_unset subroutine destroys mappings between the program number and version 
number of a remote procedure call and the ports on the host portmap daemon. 
Parameters 
prognum Specifies the program number of the remote program. 
versnum Specifies the version number of the remote program. 


implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The portmap daemon. 


The pmap_getmaps subroutine, pmap_set subroutine, svc_unregister subroutine. 
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registerrpc Subroutine 


Purpose 


Library 


Syntax 


Registers a procedure with the RPC service package. 


C Library (libe.a) 


#include <rpc/rpc.h> 

registerrpc (prognum, versnum, procnum, procname, inproc, outproc) 
u_long prognum, versnum, procnum; 

char * (*procname) (); 

xdrproc_t inproc, outproc; 


Description 


The registerrpce subroutine registers a procedure with the Remote Procedure Call (RPC) 
service package. 


If a request arrives that matches the values of the prognum parameter, the versnum 
parameter, and the procnum parameter, then the procname parameter is called with a 
pointer to its parameters, after which it returns a pointer to its static results. 


Note: Remote procedures registered in this form are accessed using the User Datagram 
Protocol/Internet Protocol (UDP/IP) transport protocol only. 


Parameters 


prognum Specifies the program number of the remote program. 
versnum Specifies the version number of the remote program. 
procnum Identifies the procedure number to be called. 
procname Identifies the procedure name. 


inproc Specifies the eXternal Data Representation (XDR) subroutine that decodes 
the procedure parameters. 


outoroc Specifies the XDR subroutine that encodes the procedure results. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of —1. 


Implementation Specifics 
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Base Operating System Reference 


registerrpc 


Related Information 
The callrpe subroutine, svcudp_create subroutine. 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 


User Datagram Protocol (UDP) in Communication Concepts and Procedures. 
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rtime Subroutine 


Purpose 
Gets remote time. 


Library 
C Library (libe.a) 


Syntax 
#include <rpc/rpc.h> 
#include <sys/types.h> 
#include <sys/time.h> 
#include <netinet/in.h> 
int rtime (addrp, timep, timeout) 
struct sockaddr_in *adarp; 
struct timeval *timep; 
struct timeval * timeout; 


Description 
The rtime subroutine consults the Internet Time Server (TIME) at the address pointed to by 
the addrp parameter and returns the remote time in the timeval structure pointed to by the 
timep parameter. Normally, the User Datagram Protoco! (UDP) protocol is used when 
consulting the time server. If the timeout parameter is specified as NULL, however, the 
routine instead uses Transmission Control Protocol (TCP) and blocks until a reply is 
received from the time server. 


Parameters oe 
addrp Points to the Internet Time Server. 


timep Points to the timeval structure. 


timeout Specifies how long the routine waits for a reply before terminating. 


Return Values 
Upon successful completion, this subroutine returns a value of 0. If unsuccessful, it returns a 
value of —1, and the error number parameter (errno) is set to reflect the cause of the error. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


Understanding Protocols for TCP/IP, User Datagram Protocol (UDP) in Communication 
Concepts and Procedures. 
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store Subroutine 


Purpose 
Places data under a key. 
Library 
DBM Library (libdbm.a) 
Syntax 
#include <dbm.h> 
store (key, content) 
datum key, content; 
Description 
The store subroutine places data under a key. 
Parameters 
key Specifies the input key. 
content Specifies the value associated with the key to store. 


Return Values 
Upon successful completion, this subroutine returns a value of 0 (zero). If unsuccessful, it 
returns a negative value. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The dbm_store subroutine. 
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svc_destroy Macro 


Purpose 
Destroys an RPC service transport handle. 
Library 
C Library (libc.a) 
Syntax 
#include <rpce/rpc.h> 
void 
svc_destroy (xprt) 
SVCXPRT *xort; 
Description 
The sve_destroy macro destroys a Remote Procedure Call (RPC) service transport handle. 
Destroying the service transport handle deallocates the private data structures, including the 
handle itself. After the svc_destroy macro is used, the handle pointed to by the xprt 
parameter is no longer defined. 
Parameter 


xprt Points to the RPC service transport handle. 


Implementation Specifics 
This macro is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The clnt_destroy macro, svc_freeargs macro. 
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svc_freeargs Macro 


Purpose 
Frees data allocated by the RPC/XDR system. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpc.h> 


svc_freeargs (xprt, inproc, in) 
SVCXPRT *xoprt; 
xdrproc_t inproc; 
char *in; 
Description 
The sve_freeargs macro frees data allocated by the Remote Procedure Call/eXternal Data 


Representation (RPC/XDR) system. This data is allocated when the RPC/XDR system 
decodes the arguments to a service procedure with the svc_getargs macro. 


Parameters 
xprt Points to the RPC service transport handle. 


inproc Specifies the XDR routine that decodes the arguments. 


in Specifies the address where the procedure arguments are placed. 


Implementation Specifics 
This macro is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The svc_getargs macro, svc_destroy macro. 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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svc_getargs Macro 


Purpose 
Decodes the arguments of an RPC request. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpc.h> 


svc_getargs (xprt, inoroc, in) 
SVCXPRT *xort; 

xdrproc_t inproc; 

char *in; 


Description 
The sve_getargs macro decodes the arguments of a Remote Procedure Call (RPC) request 
associated with the RPC service transport handle. 


Parameters 
xprt Points to the RPC service transport handle. 


inproc Specifies the eXternal Data Representation (XDR) routine that decodes the 
arguments. 


in Specifies the address where the arguments are placed. 
Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The svc_freeargs macro. 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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svc_getcaller Macro 


Purpose 
Gets the network address of the caller of a procedure. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
struct sockaddr_in * 
svc_getcaller (xprt) 
SVCXPRT *xoprt; 
Description 
The svc_getcaller macro retrieves the network address of the caller of a procedure 
associated with the Remote Procedure Call (RPC) service transport handle. 
Parameters 


xprt Points to the RPC service transport handle. 


Implementation Specifics 
This macro is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The svc_register subroutine, svc_run subroutine. 
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svc_getreqset Subroutine 


Purpose 
Services an RPC request. 


Library 
C Library (libce.a) 


Syntax 
#include <rpc/rpc.h> 
void 
svc__getreqset (rdfds) 
fd_set *rdfds; 


Description | 
The svc__getreqset subroutine is only used if a service implementor does not call the 
svc_run subroutine, but instead implements custom asynchronous event processing. The 
subroutine is called when the select subroutine has determined that a Remote Procedure 
Call (RPC) request has arrived on any RPC sockets. The svc_getreqset subroutine returns 


when all sockets associated with the value specified by the rdfds parameter have been 
serviced. 


Parameters 
rdfds Specifies the resultant read-file descriptor bit mask. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The select subroutine, svc_run subroutine. 


Sockets Overview in Communications Programming Concepts. 
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svc_register Subroutine 


Purpose 

Maps a remote procedure. 
Library 

C Library (libe.a) 
Syntax 


#include <rpc/rpc.h> 


svc_register (xprt, prognum, versnum, dispatch, protocol 
SVCXPRT *xprt; 

u_long prognum, versnum; 

void (*dispatch) (); 

int protocol; 


Description 
The svc_register subroutine maps a remote procedure with a service dispatch procedure 
pointed to by the dispatch parameter. If the protocol parameter has a value of 0, the service 
is not registered with the portmap daemon. If the protoco! parameter does not have a value 
of 0 (or if itis IPPROTO_UDP or IPPROTO_TCP), the remote procedure triple (prognum, 
versnum, and protocol parameters) is mapped to the xprt->xp_port port. 


The dispatch procedure takes the following form: 


dispatch (request, xprt) 
struct svc_req *request; 


SVCXPRT *xprt; 
Parameters 
xprt Points to a Remote Procedure Call (RPC) service transport handle. 
prognum Specifies the program number of the remote program. 
versnum Specifies the version number of the remote program. 
dispatch Points to the service dispatch procedure. 
protocol Specifies the data transport used by the service. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 
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svc_register 


Related Information 
The portmap daemon. 


The pmap_set subroutine, pmap_getmaps subroutine, svc_unregister subroutine. 


Understanding Protocols for TCP/IP, User Datagram Protocol (UDP) in Communication 
Concepts and Procedures. 
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svc_run Subroutine 


Purpose 
Waits for a Remote Procedure Call (RPC) service request to arrive. 
Library 
C Library (libc.a) 
Syntax 
#include <rpc/rpc.h> 
void 
svc_run (xpr1); 
SCVXPRT *xprt; 
Description 
The svc_run subroutine waits for an RPC service request to arrive. When a request arrives, 
the svc_run subroutine calls the appropriate service procedure with the svc_getreqset 
subroutine. This procedure is usually waiting for a select subroutine to return. 
Parameters 


xprt Points to an RPC service transport handle. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


The callrpe subroutine, registerrpce subroutine, select subroutine, svc_getreqset 
subroutine. 


Using the Intermediate Layer of RPC, Using the registerrpc Routine in Communications 
Programming Concepts. 
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svc_sendreply Subroutine 


Purpose 
Sends back the results of a remote procedure call. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
svc_sendreply (xprt, outproc, out) 
SVCXPRT *xort; 
xdrproc_t outproc; 
char “out, 
Description 
The svc_sendreply subroutine sends back the results of a remote procedure call. This 
subroutine is called by a Remote Procedure Call (RPC) service dispatch subroutine. 
Parameters 
xprt Points to the RPC service transport handle of the caller. 
outproc Specifies the eXternal Data Representation (XDR) routine that encodes the 
results. 
out Points to the address where results are placed. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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svc_unregister Subroutine 


Purpose 
Removes mappings between procedures and objects. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
void 
svc_unregister (orognum, versnum) 
u_long prognum, versnum , 
Description 
The svc_unregister subroutine removes mappings between dispatch subroutines and the 
service procedure identified by the prognum parameter and the versnum parameter. It also 
removes the mapping between the port number and the service procedure which is identified 
by the prognum parameter and the versnum parameter. 
Parameters 
prognum Specifies the program number of the remote program. 
versnum Specifies the version number of the remote program. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The pmap_unset subroutine, svc_register subroutine. 
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svcerr_auth Subroutine 


Purpose 
Indicates that the service dispatch routine cannot complete a remote procedure call due to 
an authentication error. 


Library 
RPC Library (liberpce.a) 


Syntax 
#include <rpc/rpc.h> 
void 
svcerr_auth (xort, why) 


SVCXPRT *xort; 
enum auth_stat why; 


Description 
The svcerr_auth subroutine is called by a service dispatch subroutine that refuses to 
perform a remote procedure call because of an authentication error. This subroutine sets the 
status of the RPC reply message to AUTH_ERROR. 


Parameters 
xprt Points to the Remote Procedure Call (RPC) service transport handle. 


why Specifies the authentication error. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 
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svcerr_decode Subroutine 


Purpose 
Indicates that the service dispatch routine cannot decode the parameters of a request. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
void 
svcerr_decode (xprf) 
SVCXPRT *xoprt; 
Description 
The svcerr_decode subroutine is called by a service dispatch subroutine that cannot 
decode the parameters specified in a request. This subroutine sets the status of the RPC 
reply message to the GARBAGE_ARGS condition. 
Parameter 


xprt Points to the Remote Procedure Call (RPC) service transport handle. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The svc_getargs macro. 
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svcerr_noproc Subroutine 


Purpose 


Library 


Syntax 


Indicates that the service dispatch routine cannot complete a remote procedure call because 
the program cannot support the requested procedure. 


C Library (libe.a) 


#include <rpc/rpc.h> 


void 
svcerr_noproc (xprt) 
SVCXPRT *xprt; 


Description 


Parameter 


The svcerr_noproc subroutine is called by a service dispatch routine that does not 
implement the procedure number the caller has requested. This subroutine sets the status of 
the RPC reply message to the PROC_UNAVAIL condition, which indicates that the program 
cannot support the requested procedure. 


Note: Service implementors do not usually need this subroutine. 


xprt Points to the Remote Procedure Call (RPC) service transport handle. 


Implementation Specifics 
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This subroutine is part of AIX Base Operating System (BOS) Runtime. 
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svcerr_noprog Subroutine 


Purpose 
Indicates that the service dispatch routine cannot complete a remote procedure call because 
the requested program is not registered. 

Library 
C Library (libc.a) 

Syntax 
#include <rpc/rpc.h> 
void 
svcerr_noprog (xprt) 
SVCXPRT *xprt; 

Description 
The svcerr_noprog subroutine is called by a service dispatch routine when the requested 
program is not registered with the Remote Procedure Call (RPC) package. This subroutine 
sets the status of the RPC reply message to the PROG_UNAVAIL condition, which indicates 
that the remote server has not exported the program. 
Note: Service implementors do not usually need this subroutine. 

Parameter 


xprt | Points to the RPC service transport handle. 


Implementation Specifics 


This subroutine is part of AIX Base Operating System (BOS) Runtime. 
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svcerr_progvers Subroutine 


Purpose 
Indicates that the service dispatch routine cannot complete the remote procedure call 
because the requested program version is not registered. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
void 
- svcerr_progvers (xprt) 
SVCXPRT *xoprt; 
u_long 
Description 
The svcerr_progvers subroutine is called by a service dispatch routine when the requested 
version of a program is not registered with the Remote Procedure Call (RPC) package. This 
subroutine sets the status of the RPC reply message to the PROG_ MISMATCH condition, 
which indicates that the remote server cannot support the client’s version number. 
Note: Service implementors do not usually need this subroutine. 
Parameter 


xprt Points to the RPC service transport handle. 


Implementation Specifics 
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This subroutine is part of AIX Base Operating System (BOS) Runtime. 
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svcerr_systemerr Subroutine 


Purpose 
Indicates that the service dispatch routine cannot complete the remote procedure call due to 
an error that is not covered by a protocol. 


Library 
C Library (libce.a) 


Syntax 
#include <rpc/rpc.h> 
void 


svcerr_systemerr (xprt) 
SVCXPRT *xprt; 


Description 
The svcerr_systemerr subroutine is called by a service dispatch subroutine that detects a 
system error not covered by a protocol. For example, a service dispatch subroutine calls the 
svcerr_systemerr subroutine if the first subroutine can no longer allocate storage. The 
routine sets the status of the RPC reply message to the SYSTEM_ERR condition. 


Parameter 
xprt Points to the Remote Procedure Call (RPC) service transport handle. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 
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svcerr_weakauth Subroutine 


Purpose 


Library 


Syntax 


Indicates that the service dispatch routine cannot complete the remote procedure call due to 
insufficient authentication security parameters. 


C Library (libe.a) 


#include <rpc/rpc.h> 


void 
svcerr_weakauth (xpr7) 
SVCXPRT *xort; 


Description 


Parameter 


The svcerr_weakauth subroutine is called by a service dispatch routine that cannot make 
the remote procedure call because the supplied authentication parameters are insufficient 
for security reasons. 


The svcerr_weakauth subroutine calls the svcerr_auth subroutine with the correct Remote 
Procedure Call (RPC) service transport handle (the xprt parameter). The subroutine also 
sets the status of the RPC reply message to the AUTH_TOOWEAK condition as the 
authentication error (AUTH_ERR). 


xprt Points to the RPC service transport handle. 


Implementation Specifics 


This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
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The svcerr_auth subroutine, svcerr_decode subroutine. 
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svcfd_create Subroutine 


Purpose 
Creates a service on any open file descriptor. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpe.h> 


SVCXPRT * 


svcfd_create (fd, sendsize, recvsize) 
int fd; 

u_int sendsize; 

u_int recvsize; 


Description 
The svcfd_create subroutine creates a service on any open file descriptor. Typically, this 


descriptor is a connected socket for a stream protocol such as Transmission Control 
Protocol (TCP). 


Parameters 
fd Identifies the descriptor. 


sendsize Specifies the size of the send buffer. 


recvsize Specifies the size of the receive buffer. 


Return Values 
Upon successful completion, this subroutine returns a TCP-based transport handle. If 
unsuccessful, it returns a value of NULL. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Sockets Overview in Communications Programming Concepts. 


Understanding Protocols for TCP/IP in Communication Concepts and Procedures. 
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svcraw_create Subroutine 


Purpose 
Creates a toy RPC service transport handle for simulation. 


Library 
C Library (libe.a) 


Syntax 
#include <rpc/rpc.h> 


SVCXPRT * 
svcraw_create ( ) 


Description 
The svcraw_create subroutine creates a toy Remote Procedure Call (RPC) service 
transport handle. The service transport handle is located within the address space of the 
process. If the corresponding RPC server resides in the same address space, then 
simulation of RPC and acquisition of RPC overheads, such as round-trip times, are done 
without kernel interference. 


Parameters 
This subroutine contains no parameters. 


Return Values 
Upon successful completion, this subroutine returns a pointer to a valid RPC transport 
handle. If unsuccessful, it returns a value of NULL. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The cIntraw_create subroutine. 
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svctcp_create Subroutine 


Purpose 
Creates a TCP/IP service transport handle. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
SVCXPRT * 
svctcp_create (sock, sendsz, recvsz) 
int sock; 
u_int sendsz, rcvcsz; 
Description 
The svctcp_create subroutine creates a Remote Procedure Call (RPC) service transport 
handle based on Transmission Control Protocol/Internet Protocol (TCP/IP) and returns a 
pointer to it. 
Since TCP/IP remote procedure calls use buffered I/O, users can set the size of the send 
and receive buffers with the sendsz and recvsz parameters, respectively. If the size of either 
buffer is set to a value of 0, the svctcp_create subroutine picks suitable default values. 
Parameters 


sock Specifies the socket associated with the transport. If the value of the sock 
parameter is RPC_ANYSOCK, the svctcp_create subroutine creates a new 
socket. The service transport handle socket number is set to 
xprt—>xp_ sock. If the socket is not bound to a local TCP/IP port, then this 
routine binds the socket to an arbitrary port. Its port number is set to 
xprt->xp_port. . 


sendsz Specifies the size of the send buffer. 
recvsz Specifies the size of the receive buffer. 
Return Values 


Upon successful completion, this subroutine returns a valid RPC service transport handle. If 
unsuccessful, it returns a value of NULL. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The registerrpe subroutine, svcudp_create subroutine. 


Sockets Overview in Communications Programming Concepts. 


Understanding Protocols for TCP/IP in Communication Concepts and Procedures. 
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svcudp_ create Subroutine 


Purpose 
Creates a UDP/IP service transport handle. . 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
SVCXPRT * 
svcudp_create (sock) 
int sock; 
Description 
The svcudp_create subroutine creates a Remote Procedure Call (RPC) service transport 
handle based on User Datagram Protocol/Internet Protocol (UDP/IP) and returns a pointer to 
it. 
The UDP/IP service transport handle is used only for procedures that take up to 8K bytes of 
encoded arguments or results. 
Parameter 


sock Specifies the socket associated with the service transport handle. If the 
value specified by the sock parameter is RPC_ANYSOCK, the 
svcudp_create subroutine creates a new socket and sets the service 
transport handle socket number to xprt->xp_sock. If the socket is not 
bound to a local UDP/IP port, then the svcudp_create subroutine binds the 
socket to an arbitrary port. The port number is set to xprt—>xp_port. 


Return Values 
Upon successful completion, this subroutine returns a valid RPC service transport. If 
unsuccessful, it returns a value of NULL. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The registerrpc subroutine, svctcp_create subroutine. 


Understanding Protocols for TCP/IP, User Datagram Protocol (UDP) in Communication 
Concepts and Procedures. 
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user2netname Subroutine 


Purpose 
Converts from a domain-specific user ID to an operating-system-independent network name. 


Library 
C Library (libc.a) 


Syntax 


#include <rpc/rpc.h> 


user2netname (name, uid, domain) 
char *name; 

int uid; 

char *domain; 


Description 
The user2netname subroutine converts from a domain-specific user ID to an operating 
system-independent-network name. 


This subroutine is the inverse of the netname2user subroutine. 


Parameters 
name Points to the network name (or netname) of the server process owner. 


uid Points to the caller’s effective user ID (UID). 


domain Points to the domain name. 


Return Values 
Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The host2netname subroutine, netname2user subroutine. 
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xdr_accepted_reply Subroutine 


Purpose 
Encodes RPC reply messages. 


Library 
C Library (libe.a) 


Syntax 


#include <rpe/rpc.h> 


xdr_accepted_reply (xars, ar) 
XDR *xars; 
struct accepted_reply *ar; 


Description 
The xdr_accepted_reply subroutine encodes Remote Procedure Call (RPC) reply 


messages. The routine generates message replies similar to RPC message replies without 
using the RPC program. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


ar Specifies the address of the structure that contains the RPC reply. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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xdr_array Subroutine 


Purpose 
Translates between variable-length arrays and their corresponding external representations. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/xdr.h> 


xdr_array (xdrs, arrp, sizep, maxsize, elsize, elproc) 
XDR *xars; . 

char **arrp; 

u_int *sizep; 

u_int maxsize; 

u_int e/size; 

xdrproc_t elproc; 


Description 
The xdr_array subroutine is a filter primitive that translates between variable-length arrays 
and their corresponding external representations. This subroutine is called to encode or 
decode each element of the array. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


arrp Specifies the address of the pointer to the array. If the arrp parameter is 
NULL when the array is being deserialized, XDR allocates an array of the 
appropriate size and sets the parameter to that array. 


sizep Specifies the address of the element count of the array. The element count 
cannot exceed the value for the maxsize parameter. 

maxsize Specifies the maximum number of array elements. 

elsize Specifies the byte size of each of the array elements. 

eloroc Translates between the C form of the array elements and their external 


representations. This parameter is an XDR filter. 


Return Values 
Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 


Remote Procedure Calls (RPC) 5—89 


xdr_authunix_parms 


xdr_authunix_parms Subroutine 


Purpose | 
Describes UNIX-style credentials. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpc.h> 


xdr_authunix_parms (xdrs, app) 
XDR *xars; 
struct authunix_parms *app; 


Description 
The xdr_authunix_parms subroutine describes UNIX-style credentials. This subroutine 


generates credentials without using the Remote Procedure Call (RPC) authentication 
program. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


app Points to the structure that contains the UNIX-style authentication 
credentials. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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xdr_bytes Subroutine 


Purpose 
Translates between internal counted byte arrays and their external representations. 
Library 
C Library (libce.a) 
Syntax 
#include <rpc/xdr.h> 
xdr_bytes (xdrs, sp, sizep, maxsize) 
XDR *xars; 
char **sp; 
u_int *sizep; 
u_int maxsize; 
Description 
The xdr_bytes subroutine is a filter primitive that translates between counted byte arrays 
and their external representations. This subroutine treats a subset of generic arrays, in 
which the size of array elements is known to be 1 (one), and the external description of each 
element is built-in. The length of the byte array is explicitly located in an unsigned integer. 
The byte sequence is not terminated by a null character. The external representation of the 
bytes is the same as their internal representation. 
Parameters 
xars- Points to the eXternal Data Representation (XDR) stream handle. 
sp Specifies the address of the pointer to the byte array. 
sizep Points to the length of the byte area. The value of this parameter cannot 


exceed the value of the maxsize parameter. 


maxsize Specifies the maximum number of bytes allowed when XDR encodes or 
decodes messages. 


Return Values 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_callhdr Subroutine 


Purpose 
Describes RPC call header messages. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpc.h> 


xdr_callhdr (xars, chdr) 
XDR *xars; 
struct rpc_msg *chadr,; 


Description 
The xdr_callhdr subroutine describes Remote Procedure Call (RPC) call-header messages. 


This subroutine generates call headers that are similar to RPC call headers without using 
the RPC program. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


chdr Points to the structure that contains the header for the call message. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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xdr_callmsg Subroutine 


Purpose 
Describes RPC call messages. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpc.h> 


xdr_callmsg (xdrs, cmsg) 
XDR *xars; 
struct rpc_msg *cmsg; 


Description 
The xdr_callmsg subroutine describes Remote Procedure Call (RPC) call messages. This 
subroutine generates messages similar to RPC messages without using the RPC program. 


Parameters 
xars Points to the eXternal Data Representatiion (XDR) stream handle. 


cmsg Points to the structure that contains the text of the call message. 


Return Values 
Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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xdr_char Subroutine 


Purpose 

Translates between C language characters and their external representations. 
Library 

C Library (libe.a) 
Syntax 

#include <rpc/xdr.h> 

xdr_char (xars, cp) 

XDR *xears; 

char *co; 

Description 

The xdr_char subroutine is a filter primitive that translates between C characters and their 

external representations. 

Note: Encoded characters are not packed and occupy 4 bytes each. For arrays of 
characters, the programmer should consider using the xdr_bytes, xdr_opaque, or 
xdr_string routine. 

Parameters 

xars Points to the eXternal Data Representation (XDR) stream handle. 

cp Points to the character. 


Return Values 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_destroy Macro 


Purpose 
Destroys the XDR stream pointed to by the xdrs parameter. 


Library 
C Library (libe.a) 


Syntax 
#include <rpc/xdr.h> 
void 


xdr_destroy (xdrs) 
XDR *xdrs; 


Description 7 
The xdr_destroy macro invokes the destroy routine associated with the eXternal Data 
Representation (XDR) stream pointed to by the xdrs parameter and frees the private data 
structures allocated to the stream. The use of the XDR stream handle is undefined after it is 
destroyed. 


Parameter 
xars Points to the XDR stream handle. 


Implementation Specifics 
This macro is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xdr_double Subroutine 


Purpose 
Translates between C language double-precision numbers and their external 
representations. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/xdr.h> 


xdr_double (xars, dp) 
XDR *xars; 
double *dp; 


Description 
The xdr_double subroutine is a filter primitive that translates between C double-precision 
numbers and their external representations. 


Parameters 
xadrs Points to the eXternal Data Representation (XDR) stream handle. 


do Specifies the address of the double-precision number. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics __ 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_enum Subroutine 


Purpose 
Translates between a C language enumeration (enum) and its external representation. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/xdr.h> 


xdr_enum (xars, ep) 
XDR *xars; 
enum_t *ep; 


Description 
The xdr_enum subroutine is a filter primitive that translates between a C language 
enumeration (enum) and its external representation. 


Parameters 
xars Points to the eXternal Data Representation (XDR) stream handle. 


ep Specifies the address of the enumeration data. 


Return Values 
Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_float Subroutine 


Purpose | 
Translates between C language floats and their external representations. 


Library 
C Library (libe.a) 


Syntax 


#include <rpce/xdr.h> 


xdr_float (xadrs, fp) 
XDR *xars; 
float *fp; 


Description 
The xdr_float subroutine is a filter primitive that translates between C floats (normalized 
single floating-point numbers) and their external representations. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


fo Specifies the address of the float. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information | 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_free Subroutine 


Purpose 
Deallocates, or frees, memory. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/xdr.h> 


void 

xdr_free (proc, objp) 
xdrproc_t proc; 
char *objp; 


Description 
The xdr_free subroutine is a generic freeing routine that deallocates memory. The first 
argument is the eXternal Data Representation (XDR) routine for the object being freed. The 
second argument is a pointer to the object itself. 


Note: The pointer passed to this routine is not freed, but what it points to is freed 
(recursively). 


Parameters 
proc Points to the XDR stream handle. 


objp Points to the object being freed. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xdr_getpos Macro 


Purpose 
Returns an unsigned integer that describes the current position in the data stream. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/xdr.h> 
u_int 
xdr_getpos (xdrs) 
XDR *xars; 
Description 
The xdr_getpos macro invokes the get-position routine associated with the eXternal Data 
Representation (XDR) stream pointed to by the xdrs parameter. This routine returns an 
unsigned integer that describes the current position in the data stream. 
Parameter 


xars Points to the XDR stream handle. 


Return Values 
This macro returns an unsigned integer describing the current position in the stream. In 


some XDR streams, this routine returns a value of —1, even though the value has no 
meaning. 


Implementation Specifics 
| This macro is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xdr_inline Macro 


Purpose 
Returns a pointer to the buffer of a stream pointed to by the xdrs parameter. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/xdr.h> 
long * 
x_inline (xdrs, len) 
XDR *xars; 
int /en; 
Description 
The xdr_inline macro invokes the inline routine associated with the eXternal Data 
Representation (XDR) stream pointed to by the xdrs parameter. The routine returns a 
pointer to a contiguous piece of the stream’s buffer, whose size is specified by the /en 
parameter. The buffer can be used for any purpose, but it is not data-portable. This routine 
may return a value of NULL if it cannot return a buffer segment of the requested size. 
Parameters 
xdrs Points to the XDR stream handle. 
len Specifies the size, in bytes, of the internal buffer. 


Return Values 
This macro returns a pointer to a piece of the stream’s buffer. 


Implementation Specifics 
This macro is part of AIX Base Operating asin (BOS) Runtime. 


Related Information 
Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xdr_int Subroutine 


Purpose 
Translates between C language integers and their external representations. 
Library 
C Library (libc.a) 
Syntax 
#include <rpc/xdr.h> 
xdr_int (xars, ip) 
XDR *xars; 
int */p; 
Description 
The xdr_int subroutine is a filter primitive that translates between C language integers and 
their external representations. 
Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 
ip Specifies the address of the integer. 


Return Values 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_long Subroutine 


Purpose 
Translates between C language long integers and their external representations. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/xdr.h> 
xdr_long (xdrs, /p) 
XDR *xdrs; 
long */p; 
Description 
The xdr_long filter primitive translates between C language long integers and their external 
representations. This primitive is characteristic of most eXternal Data Representation (XDR) 
library primitives and all client XDR routines. 
Parameters 


xdrs Points to the XDR stream handle. This parameter can be treated as an 
opaque handler and passed to the primitive routines. 


Ip Specifies the address of the number. 


Return Values 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_opaque Subroutine 


Purpose 
Translates between fixed-size opaque data and its external representation. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/xdr.h> 
xdr_opaque (xars, cp, cnt) 
XDR *xars; 
char *cp; 
u_int cnt; 
Description 
The xdr_opaque subroutine is a filter primitive that translates between fixed-size opaque 
data and its external representation. 
Parameters 
xars Points to the eXternal Data Representation (XDR) stream handle. 
cp Specifies the address of the opaque object. 
cnt Specifies the size, in bytes, of the object. By definition, the actual data 


contained in the opaque object is not machine-portable. 
Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_opaque_auth Subroutine 


Purpose 
Describes RPC authentication messages. 


Library 
C Library (libe.a) 


Syntax 
#include <rpc/rpc.h> 
xdr_opaque_auth (xars, ap) 


XDR *xars; 
struct opaque_auth *ap; 


Description 
The xdr_opaque_auth subroutine describes Remote Procedure Call (RPC) authentication 
information messages. It generates RPC authentication message data without using the 
RPC program. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


ap Points to the structure that contains the authentication information. 


Return Values 
Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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xdr_pmap Subroutine 


Purpose 
Describes parameters for portmap procedures. 
Library 
C Library (libc.a) 
Syntax 
#include <rpc/rpc.h> 
xdr_pmap (xars, regs) 
XDR *xdrs; 
struct pmap *regs; 
Description 
The xdr_pmap subroutine describes parameters for portmap procedures. This subroutine 
generates portmap parameters without using the portmap interface. 
Parameters 
xars Points to the eXternal Data Representation (XDR) stream handle. 
regs Points to the buffer or register where the portmap daemon stores 
information. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The portmap daemon. 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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xdr_pmaplist Subroutine 


Purpose 
Describes a list of port mappings externally. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpc.h> 


xdr_pmaplist (xdrs, rp) 
XDR *xars; 
struct pmaplist **rp; 


Description 
The xdr_pmaplist subroutine describes a list of port mappings externally. This subroutine 


generates the port mappings to Remote Procedure Call (RPC) ports without using the 
portmap interface. 


Parameters 
xadrs Points to the eXternal Data Representation (XDR) stream handle. 
rp Points to the structure that contains the portmap listings. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The portmap daemon. 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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xdr_pointer Subroutine 


Purpose 

Provides pointer chasing within structures and serializes NULL pointers. 
Library 

C Library (libc.a) 
Syntax 


#include <rpce/xdr.h> 


xdr_pointer (xdrs, objop, objsize, xdrobj/) 
XDR *xars; 

char **objpp; 

u_int objsize; 

xdrproc_t xdrobj; 


Description 
The xdr_pointer subroutine provides pointer chasing within structures and serializes NULL 
pointers. This subroutine can represent recursive data structures, such as binary trees or 


linked lists. 
Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 
objpp Points to the character pointer of the data structure. 
objsize Specifies to the size of the structure. 
xdrobj Specifies the XDR filter for the object. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xdr_reference Subroutine 


Purpose 
Provides pointer chasing within structures. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/xdr.h> 
xdr_reference (xars, pp, size, proc) 
XDR *xars; 
char **pp; 
u_int size; 
xdrproc_t proc; 
Description 
The xdr_reference subroutine is a filter primitive that provides pointer chasing within 
structures. This primitive allows the serializing, deserializing, and freeing of pointers within 
one structure that are referenced by another structure. 
The xdr_reference subroutine does not attach any special meaning to a null-value pointer 
during serialization. Attempting to pass the address of a NULL pointer can cause a memory 
error. The programmer must describe data with a two—armed discriminated union. One arm 
is used when the pointer is valid; the other arm is used when the pointer is NULL. 
Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 
pp Specifies the address of the pointer to the structure. When decoding data, 
XDR allocates storage if the pointer is NULL. 
size Specifies the byte size of the structure pointed to by the pp parameter. 
proc Filters the structure between its C form and its external representation. This 


parameter is the XDR procedure that describes the structure. 
Return Values 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_rejected_reply Subroutine 


Purpose 
Describes RPC message rejection replies. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/rpc.h> 
xdr_rejected_reply (xars, rv) 
XDR *xars; 
struct rejected_reply *rr; 
Description 
The xdr_rejected_reply subroutine describes Remote Procedure Call (RPC) message 
rejection replies. This subroutine can be used to generate rejection replies similar to RPC 
rejection replies without using the RPC program. 
Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 
rr Points to the structure that contains the rejected reply. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. . 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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xdr_replymsg Subroutine 


Purpose 
Describes RPC message replies. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/rpc.h> 


xdr_replymsg (xdrs, rmsg) 
XDR *xars; 
struct rpc_msg *rmsg; 


Description 
The xdr_replymsg subroutine describes Remote Procedure Call (RPC) message replies. 


Use this subroutine to generate message replies similar to RPC message replies without 
using the RPC program. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


rmsg Points to the structure containing the parameters of the reply message. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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xdr_setpos Macro 


Purpose 
Changes the current position in the XDR stream. 


Library 
C Library (libc.a) 


Syntax 


#include <rpc/xdr.h> 


xdr_setpos (xars, pos) 
XDR *xars; 
u_int pos; 


Description 
The xdr_setpos macro invokes the set-position routine associated with the eXternal Data 
Representation (XDR) stream pointed to by the xdrs parameter. The new position setting is 
obtained from the xdr_getpos routine. This routine returns a value of FALSE if the set 
position is impossible or if the requested position is out of bounds. 


A position cannot be set in some XDR streams. Trying to set a position in such streams 
causes the routine to fail. This routine also fails if the programmer requests a position that is 
not within the stream’s boundaries. 


Parameters 
xars Points to the XDR stream handle. 


pos Specifies a position value obtained from the xdr_getpos macro. 


Return Values 
Upon successful completion (if the stream is positioned successfully), this routine returns a 
value of 1. If unsuccessful, the routine returns a value of 0. 


Implementation Specifics 
This macro is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The xdr_getpos macro. 


Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xdr_short Subroutine 


Purpose 
Translates between C language short integers and their external representations. 


Library 
C Library (libc.a) 


Syntax 
#include <rpc/xdr.h 
xdr_short (xdrs, sp) 
XDR *xars; 
short *sp; 


Description 
The xdr_short subroutine is a filter primitive that translates between C language short 
integers and their external representations. 


Parameters 
xars Points to the eXternal Data Representation (XDR) stream handle. 


sp Specifies the address of the short integer. 


Return Values 
Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_string Subroutine 


Purpose 
Translates between C language strings and their external representations. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/xdr.h> 


xdr_string (xcrs, sp, maxsize) 
XDR *xars; 

char **so; 

u_int maxsize; 


Description 
The xdr_string subroutine is a filter primitive that translates between C language strings 
and their corresponding external representations. Externally, strings are represented as 
sequences of ASCII characters, while internally, they are represented with character 
pointers. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


sp Specifies the address of the pointer to the string. 


maxsize Specifies the maximum length of the string allowed during encoding or 
decoding. This value is set in a protocol. For example, if a protocol specifies 
that a file name cannot be longer than 255 characters, then a string cannot 
exceed 255 characters. 


Return Values 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_u_ char Subroutine 


Purpose 
Translates between unsigned C language characters and their external representations. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/xdr.h> 


xdr_u_char (xdrs, ucp) 
XDR *xoars; 
char *ucp; 


Description 
The xdr_u_char subroutine is a filter primitive that translates between unsigned C language 
characters and their external representations. 


Parameters 
xars Points to the eXternal Data Representation (XDR) stream handle. 


ucp Points to an unsigned integer. 


Return Values 5 A | | 
Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_u_int Subroutine 


Purpose 
Translates between C language unsigned integers and their external representations. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/xdr.h> 


xdr_u_int (xdrs, up) 
XDR *xars; 
u_int *up; 


Description 
The xdr_u_int subroutine is a filter primitive that translates between C language unsigned 
integers and their external representations. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


up Specifies the address of the unsigned long integer number. 


Return Values . 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_u_long Subroutine 


Purpose 
Translates between C language unsigned long integers and their external representations. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/xdr.h> 


xdr_u_long (xadrs, ulp) 
XDR *xars; 
u_long *ulp; 


Description 
The xdr_u_long subroutine is a filter primitive that translates between C language unsigned 
long integers and their external representations. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


ulo Specifies the address of the unsigned long integer. 


Return Values 


Upon successful completion, this subroutine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information | 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_u_ short Subroutine 


Purpose 
Translates between C language unsigned short integers and their external representations. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/xdr.h> 


xdr_u_short (xdrs, usp) 
XDR *xars; 
u_short *usp; 


Description | 
The xdr_u_short subroutine is a filter primitive that translates between C language 
unsigned short integers and their external representations. 


Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


usp Specifies the address of the unsigned short integer. 


Return Values 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_union Subroutine 


Purpose 
Translates between discriminated unions and their external representations. 

Library 
C Library (libe.a) 

Syntax 
#include <rpce/xdr.h> 
xdr_union (xdrs, dscmp, unp, armchoices, defaultarm) 
XDR *xars; 
enum_t *dscmp; 
char *unp; 
struct xdr_discrim *armchoices; 
xdrproc_t (*defaultarm) ; /* may equal NULL */ 

Description 
The xdr_union subroutine is a filter primitive that translates between a discriminated C 
union and its corresponding external representations. It first translates the discriminant of the 
union located at the address pointed to by the dscmp parameter. This discriminant is always 
an enum_t value. Next, the union located at the address pointed to by the unp parameter is 
translated. The armchoices parameter is a pointer to an array of xdr_discrim structures. 
Each structure contains an ordered pair of parameters[value, proc]. \f the union’s 
discriminant is equal to the associated va/ue, then the procis called to translate the union. 
The end of the xdr_discrim structure array is denoted by a routine of value NULL. If the 
discriminant is not found in the choices array, then the defaultarm procedure is called (if it is 
not NULL). 

Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 
dscmp Specifies the address of the union’s discriminant. The discriminant is an 


enum_t value. 
unp Specifies the address of the union. 
armchoices Points to an array of xdr_discrim structures. 


defaultarm A structure provided in case no discriminants are found. 


Return Values 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 


This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_vector Subroutine 


Purpose 

Translates between fixed-length arrays and their corresponding external representations. 
Library 

C Library (libe.a) 
Syntax 


#include <rpc/xdr.h> 


xdr_vector (xdrs, arrp, size, elsize, elproc) 
XDR *xars; 

char *arrp; 

u_int size, elsize; 

xdrproc_t eloroc; 


Description 
The xdr_vector subroutine is a filter primitive that translates between fixed-length arrays 
and their corresponding external representations. 


Parameters 
xdrs - Points to the eXternal Data Representation (XDR) stream handle. 
arrp Specifies the the pointer to the array. 
size Specifies the element count of the array. 
elsize Specifies the size of each of the array elements. 
elproc Translates between the C form of the array elements and their external 


representation. This is an XDR filter. 
Return Values 


Upon successful completion; this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdr_void Subroutine 


Purpose 
Supplies an XDR subroutine to the RPC system without transmitting data. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/xdr.h> 
xdr_void () 
Description 
The xdr_void subroutine has no function parameters. It may be passed to other Remote 
Procedure Call (RPC) routines that require a function parameter, where nothing is to be 
done. 
Parameters 


This subroutine contains no parameters. 


Return Values 
This subroutine always returns a value of 1. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


Understanding XDR Library Filter Primitives, Remote Procedure Call (RPC) Overview for 
Programming in Communications Programming Concepts. 
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xdr_wrapstring Subroutine 


Purpose 
Calls the xdr_string subroutine. 


Library 
C Library (libe.a) 


Syntax 


#include <rpc/xdr.h> 


xdr_wrapstring (xadrs, sp) 
XDR *xars 
char **sp 


Description 
The xdr_wrapstring subroutine is a primitive that calls the xdr_string subroutine (xdrs, sp, 
MAXUN.UNSIGNED); where the MAXUN.UNSIGNED value is the maximum value of an 
unsigned integer. The xdr_wrapstring subroutine is useful because the Remote Procedure 
Call (RPC) package passes a maximum of two eXternal Data Representation (XDR) 
routines as parameters, and xdr_string requires three. 


Parameters 
xdrs Points to the XDR stream handle. 


Sp Specifies the address of the pointer to the string. 


Return Values 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The xdr_string subroutine. 


Understanding XDR Library Filter Primitives in Communications Programming Concepts. 
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xdrmem_create Subroutine 


Purpose 
Initializes in local memory the XDR stream pointed to by the xdrs parameter. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/xdr.h> 
void 
xdrmem_create (xadrs, addr, size, op) 
XDR *xars; 
char *adodr, 
u_int size; 
enum xdr_op op; 
Description 
The xdrmem_create subroutine initializes in local memory the eXternal Data 
Representation (XDR) stream pointed to by the xdrs parameter. The XDR stream data is 
written to or read from a chunk of memory at the location specified by the addr parameter. 
Parameters 
xadrs Points to the XDR stream handle. . 
addr Points to the memory where the XDR stream data is written to or read from. 
size Specifies the length of the memory in bytes. 
op Specifies the XDR direction. The possible choices are XDR_ENCODE, 


XDR_DECODE, or XDR_FREE. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xdrrec_create Subroutine 


Purpose 
Provides an XDR stream that can contain long sequences of records. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/xdr.h> 
void 
xdrrec_create (xars, sendsize, recvsize, handle, readit, writeit) 
XDR *xars; 
u_int sendsize; 
u_int recvsize; 
char *handle; 
int (*reaad/t) (), (*writeit) (); 
Description 
The xdrrec_create subroutine provides an eXternal Data Representation (XDR) stream that 
can contain long sequences of records and handle them in both the encoding and decoding 
directions. The record contents contain data in XDR form. The routine initializes the XDR 
stream object pointed to by the xdrs parameter. 
Note: This XDR stream implements an intermediate record stream. Therefore, there are 
additional bytes in the stream to provide record boundary information. 
Parameters 
xdrs Points to the XDR stream handle. 
sendsize Sets the size of the input buffer where data is written to. If 0 is specified, the 
buffers are set to the system defaults. 
recvsize Sets the size of the output buffer where data is read from. If 0 is specified, 
the buffers are set to the system defaults. 
handle Points to the input/output buffer’s handle, which is opaque. 
readit Points to the subroutine to call when a buffer needs to be filled. Similar to 


the read system call. 


writeit Points to the subroutine to call when a buffer needs to be flushed. Similar to 
the write system call. 


Implementation Specifics 


This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
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xdrrec_endofrecord Subroutine 


Purpose 
Causes the current outgoing data to be marked as a record. 

Library 
C Library (libe.a) 

Syntax 
#include <rpc/xdr.h> 
xdrrec_endofrecord (xadrs, sendnow) 
XDR *xars; 
bool_t sendnow; 

Description 
The xdrrec_endofrecord subroutine causes the current outgoing data to be marked as a 
record and can only be invoked on streams created by the xdrrec_create subroutine. The 
data in the output buffer is marked as a completed record, and the output buffer is optionally 
written out if the value of the sendnow parameter is nonzero. 

Parameters 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 
sendnow Specifies whether the record should be flushed to the output tcp stream. 


Return Values 
Upon successful! completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The xdrrec_create subroutine. 


Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xdrrec_eof Subroutine 


Purpose 
Checks the buffer for an input stream that indicates the end of file (EOF). 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/xdr.h> 
xdrrec_eof (xars) 
XDR *xars; 
Description 
The xdrrec_eof subroutine checks the buffer for an input stream to see if it reached the end 
of the file. This routine can only be invoked on streams created by the xdrrec_create 
subroutine. 
Parameter 
xdrs Points to the eXternal Data Representation (XDR) stream handle. 


Return Values 
After consuming the rest of the current record in the stream, this routine returns a value of 1 
if the stream has no more input and a value of 0 otherwise. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The xdrrec_create subroutine. 


Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xdrrec_skiprecord Subroutine 


Purpose 
Causes the position of an input stream to move to the beginning of the next record. 
Library 
C Library (libe.a) 
Syntax 
#include <rpc/xdr.h> 
xdrrec_skiprecord (xdrs) 
XDR *xars; 
Description 
The xdrrec_skiprecord subroutine causes the position of an input stream to move past the 
current record boundary and onto the beginning of the next record of the stream. This 
subroutine can only be invoked on streams created by the xdrrec_create subroutine. The 
xdrrec_skiprecord subroutine tells the eXternal Data Representation (XDR) implementation 
that the rest of the current record in the stream’s input buffer should be discarded. 
Parameter 


xars Points to the XDR stream handle. 


Return Values 


Upon successful completion, this routine returns a value of 1. If unsuccessful, it returns a 
value of 0. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The xdrrec_create subroutine. 


Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xdrstdio_create Subroutine 


Purpose 
Initializes the XDR data stream pointed to by the xdrs parameter. 
Library 
C Library (libe.a) 
Syntax 
#include <stdio.h> 
#include <rpce/xdr.h> 
void 
xdrstdio_create (xars, file, op) 
XDR *xars; 
FILE *file; 
enum xdr_op op; 
Description 
The xdrstdio_create subroutine initializes the eXternal Data Representation (XDR) data 
stream pointed to by the xdrs parameter. The XDR stream data is written to or read from the 
standard input/output stream pointed to by the file parameter. 
Note: The destroy routine associated with such XDR stream calls the fflush function on 
the file stream, but never calls the fclose function. 
Parameters 
xdrs Points to the XDR stream handle to initialize. 
file Points to the standard I/O device which data is written to or read from. 
op Specifies an XDR direction. The possible choices are XDR_ENCODE, 


XDR_DECODE, or XDR_FREE. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Understanding XDR Non-Filter Primitives in Communications Programming Concepts. 
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xprt_register Subroutine 


Purpose 
Registers an RPC service transport handle. 
Library 
C Library (libe.a) 
Syntax 
void 
xprt_register (xprt) 
SVCXPRT *xprt; 
Description 
The xprt_register subroutine registers a Remote Procedure Call (RPC) service transport 
handle with the RPC program after the transport has been created. This subroutine modifies 
the svc_fds global variable. 
Note: Service implementors do not usually need this subroutine. 
Parameter 


xprt Points to the newly created RPC service transport handle. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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xprt_unregister Subroutine 


Purpose — 
Removes an RPC service transport handle. 
Library 
C Library (libe.a) 
Syntax 
void 
xprt_unregister (xpr?) 
SVCXPRT *xort; 
Description | 
The xprt_unregister subroutine removes a Remote Procedure Call (RPC) service transport 
handle from the RPC service program before the transport handle can be destroyed. This 
subroutine modifies the svc_fds global variable. 
Note: Service implementors do not usually need this subroutine. 
Parameter 


xprt Points to the RPC service transport handle to be destroyed. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
eXternal Data Representation (XDR) Overview for Programming in Communications 
Programming Concepts. 
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yp_all Subroutine 


Purpose 


Library 


Syntax 


Transfers all of the key-value pairs from the network information service (NIS) server to the 
client as the entire map. 


C Library (libe.a) 


#include <rpcsvc/ypcint.h> 
#include <rpcsvc/yp_prot.h> 


yp_all (indomain, inmap, incallback) 
char *indomain; 
char *inmap; 
struct ypall_CallBack *incallback { 
int (* foreach) (); 
char *data; 
} 


foreach (instatus, inkey, inkeylen, inval, invallen, indata) 


int instatus; 
char *inkey; 
int inkeylen; 
char *inval; 
int invallen; 
char *indata; 


Description 


The yp_all subroutine provides a way to transfer an entire map from the server to the client 
in a single request. The routine uses Transmission Control Protocol (TCP) rather than User 
Datagram Protocol (UDP) as with other functions in this package. This entire transaction 
takes place as a single Remote Procedure Call (RPC) request and response. The yp_all 
subroutine is used like any other NIS procedure to identify a subroutine and the map in the 
normal manner. The subroutine is supplied to process each key-value pair within the map. 


Note: The remote procedure call is returned to the yp_all subroutine only after the 
transaction is completed (successfully or unsuccessfully), or the foreach function 
decides that it does not want to see any more key-value pairs. 


Parameters 


indomain Points to the name of the domain used as input to the subroutine. 
inmap Points to the name of the map used as input to the subroutine. 


incallback Specifies the structure containing the user-defined foreach function, which 
is called for each key-value pair transfered. 


instatus Specifies either a return status value of the form NIS_TRUE or an error 
code. The error codes are defined in the <rpcsvc/yp_prot.h> header file. 


inkey Points to memory that is private to the yp_all subroutine and is overwritten 
when each new key-value pair arrives. The foreach function can use the 
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contents of the memory but does not own the memory itself. Key and value 
objects presented to the foreach function look exactly as they do in the 
server’s map. Objects not terminated by NEWLINE or NULL in the server's 
map are not terminated by NEWLINE or NULL in the client’s map. 


inkeylen Returns the length of the inkey parameter in bytes. 

inval Specifies the value as returned from the server’s database. 

invallen Specifies the size of the value in bytes. 

indata _ Specifies the contents of the incallback->data element passed to the 


yp_all subroutine. The data element shares state information between the 
foreach function and the mainline code. It is an optional parameter because 
no part of the NIS client package inspects its contents. 


Return Values 
Since the foreach subroutine is a Boolean, it returns a value of 0 (zero) to indicate that it is 
ready to be called again for additional received key-value pairs. It returns a nonzero value to 
stop the flow of key-value pairs. If the foreach function returns a nonzero value, it is not 
called again, and the yp_all subroutine returns a value of 0 (zero). 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
Remote Procedure Call (RPC) Overview for Programming in Communications Programming 


Concepts, Understanding Protocols for TCP/IP in Communication Concepts and 
Procedures. 
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yp_bind Subroutine 


Purpose 
Used in programs to call the ypbind daemon directly for processes that use backup 
strategies when NIS is not available. 

Library 
C Library (libc.a) 

Syntax 

#include <rpcesvc/ypcint.h> 

#include <rpcsvc/yp_prot.h> 

yp_bind (indomain) 

char *indomain; 

Description 

In order to use network information service (NIS), the client process must be bound to an 

NIS server that serves the appropriate domain. That is, the client must be associated with a 

specific NIS server that services the client's requests for NIS information. The NIS lookup 

processes automatically use the ypbind daemon to bind the client, but the yp_bind 
subroutine can be used in programs to call the daemon directly for processes that use 
backup strategies (for example, a local file) when NIS is not available. 

Each NIS binding allocates, or uses up, one client process socket descriptor, and each 

bound domain uses one socket descriptor. Multiple requests to the same domain use the 

same descriptor. 

Note: If a Remote Procedure Call (RPC) failure status returns from the use of the yp_bind 
subroutine, the domain is unbound automatically. When this occurs, the NIS client 
tries to complete the operation if the ypbind daemon is running and either of the 
following is true: 

e The client process cannot bind a server for the proper domain. 
e Remote procedure calls to the server fail. 
Parameter 


indomain Points to the name of the domain for which to attempt the bind. 


Return Values 


The NIS client returns control to the user with either an error or a success code if any of the 
following occurs: 


e The error is not related to RPC. 
e The ypbind daemon is not running. 


e The ypserv daemon returns the answer. 


Implementation Specifics 


This subroutine is part of AIX Base Operating System (BOS) Runtime. 
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Related Information 
The ypbind daemon, ypserv daemon. 


Remote Procedure Call (RPC) Overview for Programming in Communications Programming 
Concepts. 
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yp_first Subroutine 


Purpose 
Returns the first key-value pair from the named network information service (NIS) map in the 
named domain. 
Library 
C Library (libe.a) 
Syntax 
#include <rpcsvc/ypclint.h> 
#include <rpcsvc/yp_prot.h> 
yp_first (indomain, inmap, outkey, outkeylen, outval, outvallen) 
char *indomain; 
char *inmap; 
char **outkey; 
int *outkeylen; 
char **outval; 
int *outvallen; 
Description 
The yp_first routine returns the first key-value pair from the named NIS map in the named 
domain. 
Parameters 
indomain Points to the name of the domain used as input to the subroutine. 
inmap Points to the name of the map used as input to the subroutine. 
outkey Specifies the address of the uninitialized string pointer where the first key is 


returned. Memory is allocated by the NIS client using the malloc 
subroutine, and may be freed by the application. 


outkeylen Returns the length of the outkey parameter in bytes. 


outval Specifies the address of the uninitialized string pointer where the value 
associated with the key is returned. Memory is allocated by the NIS client 
using the malloc subroutine, and may be freed by the application. 


outvallen Returns the length of the outva/ parameter in bytes. 


Return Values 


Upon successful completion, this routine returns a value of 0 (zero). If unsuccessful, it 
returns an error as described in the <rpcsvc/yp_prot.h> header file. 
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Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The malloc subroutine. 


Remote Procedure Call (RPC) Overview for Programming in Communications Programming 
Concepts. 
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yp_get_default_domain Subroutine 


Purpose 
Gets the default domain of the node. 
Library 
C Library (libe.a) 
Syntax 
#include <rpcsvc/ypclint.h> 
#include <rpcsvc/yp_prot.h> 
yp_get_default_domain (outdomain) 
char **outdomain; 
Description 
Network information service (NIS) look-up calls require a map name and a domain name. 
The client processes can get the default domain of the node by calling the 
yp_get_default_domain routine and using the value returned in the outdomain parameter 
as the input domain (indomain) parameter for its NIS remote procedure calls. 
Parameter 


outdomain Specifies the address of the uninitialized string pointer where the default 
domain is returned. Memory is allocated by the NIS client using the malloc 
subroutine, and may be freed by the application. 


Return Values 
Upon successful completion, this routine returns a value of O (zero). If unsuccessful, it 
returns an error as described in the <rpcsve/yp_prot.h> header file. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The malloc subroutine. 


Remote Procedure Call (RPC) Overview for Programming in Communications Programming 
Concepts. 
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yp_master Subroutine 


Purpose 
Returns the machine name of the NIS master server for a map. 


Library 
C Library (libe.a) 


Syntax 
#include <rpcsvc/ypclint.h> 
#include <rpcsvc/yp_prot.h> 


yp_master (indomain, inmap,outname) 
char *indomain; : 

char *inmap; 

char **outname; 


Description 
The yp_master subroutine returns the machine name of the network information service 
(NIS) master server for a map. 


Parameters 
indomain Points to the name of the domain used as input to the subroutine. 


inmap Points to the name of the map used as input to the subroutine. 


outname Specifies the address of the unitialized string pointer where the name of the 
domain's yp_master server is returned. Memory is allocated by the NIS 
client using the malloc subroutine, and may be freed by the application. 


Return Values 
Upon successful completion, this routine returns a value of 0 (zero). If unsuccessful, it 
returns an error as described in the <rpesvc/yp_prot.h> header file. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The malloc subroutine. 


Remote Procedure Call (RPC) Overview for Programming in Communications Programming 
Concepts. 
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yp_match Subroutine 


Purpose 
Searches for the value associated with a key. 
Library 
C Library (libe.a) 
Syntax 
#include <rpcesvc/ypcint.h> 
#include <rpcsvc/yp_prot.h> 
yp_match (indomain, inmap, inkey, inkeylen, outval, outvallen) 
char *indomain; 
char *inmap; 
char *inkey; 
int inkeylen; 
char **outval; 
int *outvallen; 
Description 
The yp_match subroutine searches for the value associated with a key. The input character 
string entered as the key must match a key in the network information service (NIS) map 
exactly because pattern matching is not available in NIS. 
Parameters 
indomain Points to the name of the domain used as input to the subroutine. 
inmap Points to the name of the map used as input to the subroutine. 
inkey : Points to the name of the key used as input to the subroutine. 
inkeylen Specifies the length of the key in bytes. 
outval Specifies the address of the unitialized string pointer where the values 


associated with the key are returned. Memory is allocated by the NIS client 
using the malloc subroutine, and may be freed by the application. 


outvallen Returns the length of the outva/ parameter in bytes. 
Return Values 


Upon successful completion, this routine returns a value of 0 (zero). If unsuccessful, it 
returns an error as described in the <rpcsvc/yp_prot.h> header file. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The mailoc subroutine. 


Remote Procedure Call (RPC) Overview for Programming in Communications Programming 
Concepts. 
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yp_next Subroutine 


Key Concepts 


Purpose 


Library 


Syntax 


Returns each subsequent value it finds in the named network information service (NIS) map 
until it reaches the end of the list. 


C Library (libe.a) 


#include <rpcsvc/ypclnt.h> 
#include <rpcsvc/yp_prot.h> 


yp_next (indomain, inmap, inkey, inkeylen, outkey, outkeylen, outval, outvallen) 
char *indomain; 

char *inmap; 

char *inkey 

int inkeylen 

char **outkey; 

int *outkeylen; 

char **outvail; 

int *outvallen; 


Description 


The yp_next subroutine returns each subsequent value it finds in the named NIS map until it 
reaches the end of the list. 


The yp_next routine must be preceded by an initial yp_first subroutine. Use the outkey 
parameter value returned from the initial yp_first subroutine as the value of the inkey 
parameter for the yp_next subroutine. The inkey parameter values for subsequent calls are 
retrieved as the nth + second key-value pair. That is, each time the routine returns a 
key-value to use as the next inkey parameter. 


The concepts of first and next depend on the structure of the NIS map being processed. The 
routines do not retrieve the information in a specific order, such as the lexical order from the 
original database information files or the numerical sorting order of the keys, values, or 
key-value pairs. They do show every entry in the NIS map if the yp_first subroutine is called 
on a specific map with the yp_next subroutine called repeatedly. The process returns the 
YPERR_NOMORE message to the user to indicate that every entry in the NIS map has 
been seen once. If the same sequence of operations is performed on the same map at the 
same server, the entries are seen in the same order. 


Note: If aserver operates under a heavy load or fails, the domain can become unbound 
and then bound again while a client is running. If it binds itself to a different server, it 
can cause entries to be seen twice or not be seen at all. The domain rebinds itself to 
protect the enumeration process from being interrupted before it completes. Avoid 
this situation by returning all of the keys and values with the yp_all subroutine. 


Parameters 
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indomain Points to the name of the domain used as input to the subroutine. 


inmap Points to the name of the map used as input to the subroutine. 
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inkey Points to the key that is used as input to the subroutine. 
inkeylen Returns the length of the inkey parameter in bytes. 
outkey Specifies the address of the unitialized string pointer where the first key is 


returned. Memory is allocated by the NIS client using the malloc 
subroutine, and may be freed by the application. 


outkeylen Returns the length of outkey in bytes. 


outval Specifies the address of the unitialized string pointer where the values 
associated with the key are returned. Memory is allocated by the NIS client 
using the malloc subroutine, and may be freed by the application. 


outvallen Returns the length of the outva/ parameter in bytes. 
Return Values 


Upon successful completion, this routine returns a value of 0. If unsuccessful, it returns an 
error as described in the <rpcsvc/yp_prot.h> header file. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The malloc subroutine, yp_all subroutine, yp_first subroutine. 


Remote Procedure Call (RPC) Overview for Programming in Communications Programming 
Concepts. 
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yp_order Subroutine 


Purpose 
Returns the order number for a network information service (NIS) map that identifies when 
the map was built. 


Library 
C Library (libe.a) 


Syntax 
#include <rpcsvc/ypcint.h> 
#include <rpcsvc/yp_prot.h> 


yp_order (indomain, inmap, outorden 
char *indomain; 

char *inmap; 

int *outorder; 


Description 
The yp_order subroutine returns the order number for an NIS map that identifies when the 


map was built. The number determines whether the local map is the most current version or 
the master NIS database has a more current one. 


Parameters 
indomain Points to the name of the domain used as input to the subroutine. 


inmap Points to the name of the map used as input to the subroutine. 


outorder Points to the returned order number, which is a ten-digit ASCII integer that 
represents the AIX time, in seconds, when the map was built. 


Return Values 
Upon successful completion, this routine returns a value of 0 (zero). If unsuccessful, it 
returns an error as described in the <rpcsvc/yp_prot.h> header file. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 


Remote Procedure Call (RPC) Overview for Programming in Communications Programming 
Concepts. 


5-142 Base Operating System Reference 


yp_unbind 


yp_unbind Subroutine 


Purpose 
Manages socket descriptors for processes that access multiple domains. 
Library 
C Library (libe.a) 
Syntax 
#include <rpcsvc/ypclint.h> 
#include <rpcsvc/yp_prot.h> 
void yp_unbind (indomain) 
char *indomain; 
Description 
The yp_unbind subroutine is available to manage socket descriptors for processes that 
access multiple domains. When the yp_unbind subroutine is used to free a domain, all 
per-process and per-node resources that were used to bind it are also freed. 
Parameter 


indomain Points to the name of the domain used as input to the subroutine. 


Return Values 
Upon successful completion, this routine returns a value of 0 (zero). If unsuccessful, it 
returns an error as described in the <rpcsvc/yp_prot.h> header file. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The ypbind daemon. 
The yp_bind subroutine. 


Sockets Overview in Communications Programming Concepts. 


Remote Procedure Calls (RPC) 5-143 


yp_update 


yp_update Subroutine 


Purpose 
Used to make changes to the network information service (NIS) map. 


Library 
C Library (libce.a) 


Syntax 
#include <rpcsvc/ypcint.h> 
#include <rpcsvc/yp_prot.h> 


yp_update (indomain, inmap, ypop, inkey, inkeylen, indata, indatalen) 
char *indomain; 

char *inmap; 

unsigned ypop; 

char *inkey; 

int inkeylen; 

char *indata; 

int indatalen; 


Description 
The yp_update subroutine is used to make changes to the NIS map. The syntax is the 


same as that of the yp_match subroutine except for the extra parameter ypop which may 
take on one of the following four values: 


ypop _INSERT Inserts the key-value pair into the map. If the key already exists in the 
map, the yp_update subroutine returns a value of YPERR_KEY. 


ypop_CHANGE Changes the data associated with the key to the new value. If the key 


is not found in the map, the yp_update subroutine returns a value of 
YPERR_KEY. 


ypop_STORE Stores an item in the map whether or not it already exists. No error will 
be returned if the key exists already or does not exist. 


ypop_DELETE Deletes an entry from the map. 


Note: This routine depends upon secure Remote Procedure Call (RPC), and will not work 
unless the network is running secure RPC. 


Parameters 
indomain Points to the name of the domain used as input to the subroutine. 


inmap Points to the name of the map used as input to the subroutine. 
ypop Specifies the update operation to be used as input to the subroutine. 
inkey Points to the input key to be used as input to the subroutine. 


inkeylen — Specifies the length of the inkey parameter in bytes. 
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indata Points to the data used as input to the subroutine. 


indatalen Specifies the length of the data in bytes used as input to the subroutine. 


Return Values 
Upon successful completion, this routine returns a value of 0. If unsuccessful, it returns an 
error as described in the <rpcsvc/yp_prot.h> header file. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The /etc/yp/updaters file. 


The yp_match subroutine. 
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yperr_string Subroutine 


Purpose 
Returns a pointer to an error message string. | 
Library 
C Library (libe.a) 
Syntax 
#include <rpcsvc/ypclint.h> 
#include <rpcsvc/yp_prot.h> 
char *yperr_string (incode) 
int incode; 
Description 
The yperr_string routine returns a pointer to an error message string. The error message 
string is null-terminated but contains no period or new-line escape characters. 
Parameter 


incode Contains network information service (NIS) error code as described in the 
<rpcsvc/yp_prot.h> header file. 


Return Values 


This routine returns a pointer to an error message string corresponding to the incode 
parameter. 


Implementation Specifics 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information _ 
Remote Procedure Call (RPC) Overview for Programming in Communications Programming 
Concepts. 
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ypprot_err Subroutine 


Purpose 
Takes a network information service (NIS) protocol error code as input, and returns an error 
code to be used as input to a yperr_string subroutine. 
Library 
C Library (libe.a) 
Syntax 
#include <rpcsvc/ypcint.h> 
#include <rpcsvc/yp_prot.h> 
ypprot_err (incode) 
u_int incode; 
Description 
The ypprot_err subroutine takes an NIS protocol error code as input, and returns an error 
code to be used as input to a yperr_string subroutine. 
Parameter 


incode Specifies an NIS protocol error used as input to the subroutine. 


Return Values 
This routine returns a corresponding error code to be passed to the yperr_string 
subroutine. 


Implementation Specifics _ 
This subroutine is part of AIX Base Operating System (BOS) Runtime. 


Related Information 
The yperr_string subroutine. 


Remote Procedure Call (RPC) Overview for Programming in Communications Programming 
Concepts. 
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aix_exec Function 


Purpose 
Executes AIX programs and commands from within a virtual G machine environment. 
Syntax 
(int) aix_exec (Command) 
string Command; 
Description 
The aix_exec function uses the AIX exec subroutine to execute programs and commands. 
These execute as separate processes outside the VGM environment. The standard input 
file is not opened for the spawned processes, so they cannot read input. The VGM does not 
wait for the spawned process to terminate. 
Parameter 


Command Specifies the AIX command to be invoked. This parameter must be a string. 


Return Values 
The aix_exec function returns the process ID of the spawned process. There are no error 
return codes. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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alloc Function 


Purpose 
Makes a specified amount of storage space available and returns a pointer to the newly 
allocated space. 

Syntax 
(pointer) alloc (Words) 
int Words; 

Description 
The alloc function dynamically allocates a specified amount of storage space in memory. 
This space is measured in units of 32 bits. These units are also referred to as words. Once 
it allocates space, the alloc function returns a pointer that points to the newly allocated 
space. 
Note: This is useful for building arrays. 

Parameter 


Words Specifies the amount of space, in units of 32 bits, to be made available. This 
parameter must be an integer data type. 


Return Value 
The alloc function returns a pointer that points to the allocated space. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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ascii Function 


Purpose 
Returns the integer ASCII value of the first character in the specified string. 
Syntax 
(int) ascii (String) 
string String; 
Description 
The ascii function returns the integer ASCII value of the first character in the parameter 
string. It is useful, in conjunction with the mid function, for handling binary data embedded 
within a string. 
Parameter 
String Specifies the string in which the ASCII value of the first character is 
requested. 


Return Value 
The ascii function returns the integer ASCII value of the first character in the parameter 
String. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The mid function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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base_type Function 


Purpose 
Takes a Management Information Database (MIB) numeric—format variable name or 
numeric—format instance ID and returns a number that indicates its base type. 


Syntax 
(int) base_type (Object/D) 
string ObjectiD; 


Description 
The base_type function takes an MIB numeric—format variable name or numeric—format 
instance ID and returns a number that indicates its base type. 


Note: See RFC 1066 for further information. 


Parameter 


ObjectlD Specifies the MIB numeric—format variable name or numeric—format 


instance ID whose base type is queried. This parameter must be a string 
Gata type. 


Return Values 
If the parameter identifies an integer, the base_type intrinsic function returns a 1. If the 
parameter identifies a string, the base_type intrinsic function returns a 2. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Understanding the Simple Network Management Protocol (SNMP), Understanding the 
Management Information Base (MIB), Understanding Terminology Related to Management 
Information Base (MIB) Variables, Working with Management Information Base (MIB) 
Variables in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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close Function 


Purpose 
Closes the open file indicated by the specified file descriptor. 


Syntax 
(int) close (FileDescripton 
int FileDescriptor, 


Description 
The close function closes the open file indicated by the FileDescriptor parameter. 


Parameter 
FileDescriptor File descriptor. This parameter must be an integer. 


Return Values 
The close function returns 0 (zero) if the file closes successfully; otherwise, it returns —1. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The fopen function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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create SNMP_port Subroutine 


Purpose 
Creates a UDP socket to communicate with an SNMP agent. 


Syntax 


extern struct sockaddr_in snmp_dest; 
extern int SNMP_port; 

int create_SNMP_port (agent_address) 
unsigned long agent_address; 


Description 
The create_SNMP_port subroutine creates a UDP socket and prepares the structure 


specified by the snmp_dest parameter for communication with an SNMP agent specified by 
the agent_address parameter. 


Note: This subroutine should only be called once. It does not support opening multiple 
sockets for concurrent communication with several agents. 


Parameter 
agent_address Specifies the agent with which to communicate. 


External Variables 


snmp_dest The structure that contains the socket address prepared for communication 
by the create_SNMP_port subroutine. 


SNMP_port _ The file descriptor that denotes the UDP socket created for communication 
by the create_SNMP_port subroutine. 


Return Values 
. lf an error occurs, the create_SNMP_port subroutine returns —1. Otherwise, it returns 0 
(zero). 


Note: The file descriptor for the socket is stored in the SNMP_port external variable. A 
socket address is stored in the snmp_dest external variable. 


Implementation Specifics 
This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


Related Information 
The SNMP_errormsg array. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP) in Communications Programming Concepts. 
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ctime Function 


Purpose 
Generates a text string that corresponds to an integer expression of time. 

Syntax 
(string) ctime (TimeExpy 
int TimeExpr, 

Description 
The ctime function generates a text string that corresponds to the time specified by the 
TimeExpr parameter. Note that the ctime function does not add a new-line character to the 
end of the string, while the C library function does. 

Parameter 


TimeExpr Specifies the time to be expressed. This parameter must be an integer. 


Return Value 
The ctime function returns a string of text characters that expresses the time as an integer. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The time function. 


Aiphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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dep_info Function 


Purpose 
Returns information about a display element. 

Syntax 
(string) dep_info (E/ementName) 
string ElementName; 

Description 
The dep_info function returns information about a display element. If the name passed 
does not refer to a display element, the null string is returned. The type of string returned 
depends on the type of the display element specified. 

Parameter 


ElementName Specifies the name of the element about which the dep_info function 
is to get information. This parameter must be a string data type. To 
name a link, this parameter takes the form: 


hostnamel<—>hostname2 


Return Values 
Returns information about a specific display element, for instance: 


1. When information is requested on a node, the xgmon program returns the following: 


x,y|n: 


In this example, the “n” indicates the display element is anode. The x and y coordinates 
indicate the position of the display element on the screen. 
2. When information is requested on a host, the xgmon program returns the following: 


x,y|h:addrl,addr2,addr3,... 


In this example, the “h” indicates the display element is a host. The x and y coordinates 


indicate the position of the display element on the screen. Also, the IP addresses 
associated with the host are listed. 


3. When information is requested on a link, the xgmon program returns the following: 


x,y|l:from_addr,to addr 
In this example, the | (bar) indicates the display element is a link. The x and y 
coordinates are meaningless in this case, but the format is identical to the previous 


examples to permit easier parsing. Also, the IP addresses indicate where each end of 
the link connects. 


4. If the name passed does not refer to a display element, the null string is returned. 
Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


6—10 Base Operating System Reference 


dep_info 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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dotaddr Function 


Purpose 
Returns a string representing the IP address in dot notation. 


Syntax 


(string) dotaddr (/PAddress) 
int /PAddress; 


Description 
The dotaddr function returns a string representing the specified IP address in dot notation. 


Parameter 
IPAddress Specifies the IP address. This parameter must be an integer. 


Return Value 


The dotaddr function returns a string representing the IP address in dot notation (for 
example, 129.35.1.1). 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The hostname function, ipaddr function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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draw_line Function 


Purpose 
Draws a line. 

Syntax 
(int) draw_line (x7, y1, x2, y2, Width, Color) 
int x1, y1, x2, y2; 
int Width; 
int Color, 

Description 
The draw_line function draws a line from pixel point (x7,y71) to pixel point (x2,y2) on the 
display associated with the virtual G machine. The width of the line is specified by the Width 
parameter,and is drawn in the color or style indicated by the Co/or parameter. Ona 
monochrome display, this can be either 1 or 2, indicating a solid or dotted line, respectively. 
On color displays, the color specification can be 1, 2, 3, 4, 5, 6, 7, or 8 corresponding to the 
color for up, unknown, down, background, white, acknowledged, ignored, and inactive, 
respectively. 

Parameters 
x1, y1, x2, y2 

Indicate, in pixel points, the exact location of a line on the display. These 
parameters are integers. 

Width Indicates the width, in pixel points, of the line. This parameter is an integer. 
Color Indicates the color of the line or, if the display is monochrome, indicates 


whether the line is solid or dotted. This parameter is an integer. 


Return Values 
If the line displays successfully, the draw_line function returns 0 (zero). Otherwise, the 
draw_line function returns —1. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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draw_ string Function 


Purpose 
Enables the display of formatted output in color. 
Syntax 
(int) draw_string (Format, Argument ..., Color) 
string Format; 
DataType Argument, 
int Color, 
Description 
The draw_string function is used to display formatted output on the graphics window 
associated with the virtual G machine. The string is drawn in the color indicated by the Co/or 
parameter. On a color display, this can be 1, 2, 3, 4, 5, 6, 7, or 8 corresponding to the color 
for up, unknown, down, background, white, acknowledged, ignored, and inactive, 
respectively. On a monochrome display, the color specification can only be white. 
Parameters 
Format This parameter must be a string. 
Argument This parameter can be an integer, string, or pointer. 
Color Indicates the color of the string. If the display is monochrome, 


the color is white. This parameter is an integer. 
Note: The Format string can be specified as permitted by the printf subroutine. 


Return Values 


If the string displays successfully, the draw_string function returns 0 (zero). If the string fails 
to display, the draw_string function returns —1. 


Examples 
1. draw_string ("%c%c%c%s”, 27, 1, 1, “hello world”, 3); 


In this example, the draw_string function writes hello world to the upper left corner 
in the color for down. 


2. draw_string ("%s”, “hello world”, 2); 


In this example, the draw_string function writes hello world at the current cursor 
position in the color for unknown. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 
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Related Information 
The printf command. 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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exec Function 


Purpose 


Syntax 


Allows a virtual G machine to start execution of a library command in another virtual G 
machine or allows a virtual G machine to issue a system command. 


(int) exec (Command) 
string Command; 


Description 


Parameter 


The exec function allows a virtual G machine to start execution of a library command in 
another virtual G machine or to issue a system command, such as the compile command. 

If the exec function successfully executes a library command, it returns the machine ID of 
the virtual G machine on which the command is to be executed. If there are no free virtual G 
machines, the exec function returns —1. If a system command is invoked, a 0 (zero) is 
returned. If the command is not recognized as a system command or a library command, 
the exec function returns —2. 


Command Specifies the library command or system command to be executed. 
This parameter must be a string data type. 


Return Values 


Machine ID lf a library command is successfully executed, the exec function 
returns the ID of the virtual G machine on which the command is to be 
executed. 

0 This value is returned if a system command is invoked. 

—1 This value is returned if no machines are available to execute the 


library command. 


-2 This value is returned if the command is not recognized as a system 
command or a library command. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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extract_ SNMP_name Subroutine 


Purpose 
Extracts the variable name portion of a numeric—format instance ID. 

Syntax 
char *extract_SNMP_name (instance_id) 
char *instance_id; 

Description 
An instance ID consists of a variable name followed by an instance value. The 
extract_SNMP_name subroutine accepts instance IDs in numeric format, and returns a 
pointer to the numeric—format variable name. The returned name is terminated by a . (dot) 
so that an instance value can be directly concatenated to it. 

Parameter 


instance_id A pointer to an instance ID in numeric format. 


Return Values 
lf the instance_id parameter contains a variable name registered in the /etc/mib_desc file, a 


pointer to that name (in numeric format) is returned. Otherwise, a pointer to the empty string 
is returned. 


Example 
1. The following line returns a pointer to "1.3.6.1.2.1.4.21.1.10.": 


extract, SNMP name ("1.326.1.2.1.4.2141.10.127.0.0.17)5 


Note: An instance ID value of "ipRouteAge.127.0.0.1” is invalid since the 
instance_id parameter must be numeric. 


Implementation Specifics 
This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


File 

/etc/mib_desc Defines the Management Information Base (MIB) variables. 
Related Information 

The SNMP_errormsg array. 

The lookup_SNMP_group subroutine, lookup_ SNMP_name subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP), Understanding the Management Information Base (MIB), Understanding 
Terminology Related to Management Information Base (MIB) Variables, Working with 
Management Information Base (MIB) Variables in Communications Programming Concepts. 
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flush_trap Function 


Purpose 
Flushes the current trap that is being processed. 

Syntax 
(int) flush_trap (Flag) 
int Flag; 

Description 
The flush_trap function is used to flush the current trap that is being processed. It returns 
the number of traps pending (this number is also available in the traps_pending global 
variable.) Normally, 0 (zero) is passed, and only the current trap is flushed. If a value other 
than 0 (zero) is passed, all of the pending traps are flushed. 

Parameter 


Flag Specifies either a zero or nonzero integer. 


Return Value 
Returns the number of traps pending. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 


Working with Virtual G Machine (VGM) Variables in Communications Programming 
Concepts. 
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font_height Function 


Purpose 
Returns the height, in pixels, of the font being used in the graphics window associated with a 
virtual G machine. 
Syntax 
(int) font_height(0) 
Description 
The font_height function returns the height, in pixels, of the font being used in the graphics 
window associated with the virtual G machine in which the program is running. 
Parameter 


Dummy parameter 0 (zero) is required. 


Return Values 


The font_height function returns the height of the font being used in the graphics window. If 
there is no window associated with the virtual G machine, —1 is returned. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The font_width function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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font_width Function 


Purpose 
Returns the width, in pixels, of the font being used in the graphics window associated a 
virtual G machine. 
Syntax 
(int) font_width(0) 
Description 
The font_width function returns the width, in pixels, of the font being used in the graphics 
window associated with the virtual G machine in which the program is running. 
Parameter 


Dummy parameter 0 (zero) is required. 


Return Values 
The font_width function returns the width of the font being used in the graphics window. If 
there is no window associated with the virtual G machine, —1 is returned. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The font_height function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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fopen Function 


Purpose 
Opens the file indicated by the specified file name. 
Syntax 

(int) fopen (File, AccessMode) 

string File; 

string AccessMode; 

Description 

The fopen function is used to open the file specified by the File parameter. Three values for 

AccessModeé are recognized. The first two open the file for writing using the print... to 

statement; the third opens the file for read using the read function. 

The integer value returned is a file descriptor to be used in the to clause of a print 

statement or passed as an argument to the read function. Files are automatically closed 

when a virtual G machine is halted but can be closed by the close function. 

Note: Although xgmon normally runs setuid to the root user, file opens are validated with 
the permissions associated with the user running the xgmon client instead of the 
unlimited permissions associated with root privileges. 

Parameters 

File The name of the file including the path name. This parameter must be 
a string data type. 

AccessMode Indicates how the file is to be opened as follows: 
w Creates or truncates a file. 
a Appends a file. If the file does not exist, append mode creates 

the file. 

r Reads a file. 


This parameter must be a string data type. 


Return Values 


Returns the file descriptor (integer value) if the file opens successfully, or returns 0 (zero) if 
the file fails to open. 


Example 
1. int fd; 


string filename; 
filename="my file”; 
fd = (int) fopen (filename, "r”); 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 
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fopen 


Related Information 
The close function, read function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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get_deps Function 


Purpose 
Returns a list of display elements that are grouped under a particular node. 

Syntax 
(string) get_deps (ElementName) 
string ElementName; 

Description 
The get_deps function makes available the hierarchy of display elements that make up the 
current active topology description. This function is passed the name of a node and returns 
a list of display elements that are grouped underneath it. The pseudo-root element is 
specified by the null string. 
If the specified display element does not exist or is not a node with display elements 
grouped under it, the null string is returned. 

Parameter 


ElementName Specifies the name of the node about which information is desired. 
This parameter must be a string data type. 


Return Values 
Returns the null string if the specified display element does not exist or if the specified 
display element is not a node with display elements grouped under it. Otherwise, the 
get_deps function returns a list of the display elements that are grouped under the display 
element. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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get_MIB_base_type Subroutine 


Purpose 
Returns a value indicating the base type of a Management Information Base (MIB) variable. 
Syntax 
int get_MIB_base_type (object_id) 
char *object_id; 
Description 
The get_MIB_base_type subroutine returns a value indicating the base type of the specified 
variable. These types are defined by RFC 1066 for the standard MIB. 
Parameter 


object_id Specifies the MIB variable name in numeric format. 


Return Values 


If the numeric-format MIB variable name is unrecognized, —1 is returned. Otherwise, one of 
the following values is returned: 


1 unsigned long 
2 string. 


Implementation Specifics 


This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


File 


/etc/mib_desc Defines the Management Information Base (MIB) variables. 


Related Information 
The SNMP_errormsg array. 


The get_MIB_name subroutine, get_MIB_variable_type subroutine, lookup_SNMP_name 
subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP), Understanding the Management Information Base (MIB), Understanding 
Terminology Related to Management Information Base (MIB) Variables, Working with 
Management Information Base (MIB) Variables in Communications Programming Concepts. 
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get_MIB_group Function 


Purpose 
Finds the set of all Management Information Base (MIB) variable names that contain a given 
text string as a prefix. 

Syntax 
(pointer) get_MIB_group (Prefix) 
string Prefix; 

Description 
The get_MIB_group intrinsic function searches all text-format names in the /etc/mib_desc 
file and extracts those that contain the string specified by the Prefix parameter. The search 
is not case-sensitive. A pointer to an array of the numeric—format names is returned. Each 
numeric—format name is terminated with a . (dot) so that an instance can be directly 
concatenated with it. 
Note: See RFC 1066 for further information. 

Parameter 


Prefix Specifies a prefix of a group of MIB variable names in text format. This 
parameter must be of the string data type. 


Return Values 


lf matching names are found, a pointer to an array of strings containing the matching names 
is returned. Otherwise, a pointer to the empty string (””) is returned. 


Example 


1. The following example obtains a list of MIB variables that contain the if prefix, and prints 
out all the numeric—format variables in the list: 


pointer list; 
string variable; 
int a 


list = (pointer) get _MIB group("if”); 
variable = list[0]; 


i= 0; 

while (variable != "") { 
print ”"\nvariable = %s”, variable; 
i=i+d1; 
variable = list[{i]; 

} 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol Manager in AIX 
Network Management/6000. 
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Files 


/etc/mib_desc Defines the Management Information Base (MIB) variables. The user 
specifies a time-to-live (TTL) value (in seconds) for each variable. 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Understanding the Simple Network Management Protocol (SNMP), Understanding the 
Management Information Base (MIB), Understanding Terminology Related to Management 
Information Base (MIB) Variables, Working with Management Information Base (MIB) 
Variables in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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get_MIB_name Subroutine 


Purpose 
Returns the text name of a Management Information Base (MIB) variable. 

Syntax 
char *get_MIB_name (var_name) 
char *var_name; 

Description 
The get_MIB_name subroutine maps the numeric-format variable name specified by the 
var_name parameter to the corresponding text name. These names are defined by RFC 
1066 for the standard MIB. 

Parameter 


var_name Specifies the MIB variable name in numeric format. 


Return Values 
The text name corresponding to the numeric-format variable name specified by the 


var_name parameter is returned. If the variable name is unrecognized, the null string is 
returned. 


Example 
1. If the var_name parameter is "1.3.6.1.2.1.1.1”, a pointer to the string 
"sysDescr” is returned. 


Note: A variable name value of "sysDescr” is invalid since the var_name parameter 
must be in numeric format. 


Implementation Specifics 


This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


File 

/etc/mib_desc Defines the Management Information Base (MIB) variables. 
Related Information 

The SNMP_errormsg array. 

The get_MIB_base_type subroutine, get_MIB_variable_type subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP), Understanding the Management Information Base (MIB), Understanding 
Terminology Related to Management Information Base (MIB) Variables, Working with 
Management Information Base (MIB) Variables in Communications Programming Concepts. 
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get_MIB_variable_type Subroutine 


Purpose 
Returns a value indicating the variable type of a Management Information Base (MIB) 
variable. 

Syntax 
int get_MIB_variable_type (var_name) 
char *var_name; 

Description 
The get_MIB_variable_type subroutine returns a value indicating the type of the specified 
variable. These types are defined by RFC 1066 for the standard MIB. 

Parameter 


var_name Specifies the MIB variable name in numeric format. 


Return Values 
If the variable name is unrecognized, —1 is returned. Otherwise, one of the following values 


is returned: 

1 number 

2 string 

3 object identifier 
4 empty 

5 internet address 
6 counter 

7 gauge 

8 time ticks. 


Implementation Specifics 
This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


File 


/etc/mib_desc Defines the Management Information Base (MIB) variables. 
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Related Information 
The SNMP_errormsg array. 


The get_MIB_base_type subroutine, get_MIB_name subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP), Understanding the Management Information Base (MIB), Understanding 
Terminology Related to Management Information Base (MIB) Variables, Working with 
Management Information Base (MIB) Variables in Communications Programming Concepts. 
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get_primary Function 


Purpose 
Returns the current primary address associated with the specified host. 


Syntax 


(int) get_primary (HostName) 
string HostName; 


Description 
The get_primary function returns the current primary address associated with the specified 
host. The primary address can be changed by the next_alternate function. These two 
functions are used to implement adaptive, alternate addresses, permitting xgmon 
applications to adapt to the failure of an interface on a network element the xgmon program 
is monitoring. The designated host should be fully described by the current topology 
description. Most applications would want to use this function instead of the ipaddr function. 


Parameter 


HostName Specifies the name of the host to be queried. This parameter must be a 
string data type. 


Return Value 
Returns the primary address of the host queried. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The next_alternate function, ipaddr function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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getenv Function 


Purpose 
Obtains the value of a user-defined environment variable for a host. 
Syntax 
(string) getenv (DisplayElementName, VariableName) 
string DisplayElementName; 
string VariableName; 
Description 
The getenv function retrieves the value of a user-defined environment variable associated 
with the specified display element. The xgmon program recognizes the RIGHTCLICK 
environment variable name as being associated with the name of the library command that 
should be run when the display element is double—clicked using the right mouse button. 
Parameters 


DisplayElementName 


Specifies the name or IP address (in dot notation) of the display 
element for which an environment variable is to be retrieved. This 
parameter must be a string data type. 


VariableName Specifies the name of the user-defined environment variable. This 
parameter must be a string data type. 


Return Values 
Returns the value of the user-defined environment variable in string format. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The getenv library command, load_env library command, setenv library command. 


The setenv intrinsic function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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group_dep Function 


Maps a dynamically created node or host to the topology display window. 


(int) group_dep (Node, ElementName) 


The group_dep function maps a dynamically created node or host to the topology display. 
The normal sequence of events is for a display element to be created by the make_dep 
function or by the xgmon program in the /earn mode. Then, the move_dep function 
positions the element and finally, the group_dep function maps the element to the topology 


Specifies the name of the node under which the display element specified 
by the ElementName parameter is to be mapped to the display. This 
parameter must be a string data type. The pseudo-root node is indicated 
by passing the null string as the value of the Node parameter. 


Purpose 
Syntax 

string Node; 

string ElementName; 
Description 

display. 
Parameters 

Node 

ElementName 


Return Values 


Specifies the name of the display element to be mapped to the topology 
display. This parameter must be a string data type. 


Returns an integer value as follows: 


0 (zero) 


The group_dep function successfully groups the display element specified 
by the ElementName parameter under the node specified by the Node 
parameter. 


The ElementName parameter does not specify a display element when 
grouping under the pseudo-root. 


The node defined by the Node parameter is not a display element. 


The node defined by the Node parameter is invalid because it has an IP 
address; that is, the parameter specified is a host, not a node. 


The ElementName parameter does not specify a display element when 
grouping under a node other than the pseudo-root. 


The display element specified by the ElementName parameter is already 
grouped under a node. 


implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 
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group _dep 


Related Information 
The learn subcommand, the make_depsubcommand, move_dep subcommand. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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gw_var Function 


Purpose 
Extracts the value of the specified Management Information Base (MIB) numeric—format 
instance ID for the specified host from the internal database. 
Syntax 
(DataType) gw_var (HostName, Object/D) 
string HostName; 
string ObjectiD; 
Description 
The gw_var intrinsic function extracts the value of the specified HostName, Object/D pair 
from the internal database. 
Notes: 

1. If the MIB variable’s time-to-live (TTL) has expired, there will be no value for the 
specified HostName, Object/D pair in the internal database. The TTL value is 
specified in the /etc/mib_desc file. 

2. See RFC 1066 for further information. 

Data Type 
The data type can be an integer, a string, or a pointer. 
Parameters 


HostName Specifies the name or IP address (in dot notation) of a host. The value 
of this parameter must be a string data type. 


ObjectID Specifies the MIB numeric—format instance ID. The value of this 
parameter must be a string data type. 


Return Values 
The return value is the value of the MIB variable. Since the gw_var function can return 
variables of any type (such as integers, strings, or pointers), it is up to the programmer to 
know which of these formats is used for the stored data. To find out which type to expect, 
use the base_type function. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


File 
/etc/mib/_desc Defines the Management Information Base (MIB) variables that the 


xgmon program should recognize and handle. The user also specifies 
a time-to-live (TTL) value (in seconds) for each variable. 
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Related Information 
The base_type function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Understanding the Simple Network Management Protocol (SNMP), Understanding the 
Management Information Base (MIB), Understanding Terminology Related to Management 
Information Base (MIB) Variables, Working with Management Information Base (MIB) 
Variables in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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hexval Function 


Purpose 
Returns the integer value represented by the text characters in the specified string. 
‘Syntax 
(int) hexval (HexString) 
string HexString; 
Description 
The hexval function returns the integer value represented by the text characters in the 
HexString parameter. It assumes the number is to be interpreted as a hexadecimal number 
and accepts both uppercase and lowercase representations of hex digits. 
Note: If acharacter is specified in the string that is not a valid hex digit, it is ignored. 
Parameter 


HexString Specifies the hex string to be queried. This parameter must be a 
string data type. 


Return Value 


This hexval function returns the integer value represented by the text characters in the 
specified string. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The num function, val function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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highlight_dep Function 


Purpose 
Permits a virtual G machine to temporarily highlight a display element. 


Syntax 


(int) highlight_dep (ElementName) 

(int) highlight_dep (E/ementName, TimeOut) 

(int) highlight_dep (ElementName, TimeOut, State) 
string ElementName; 

int TimeOut; 

string State; 


Description 
The highlight_dep function permits a virtual G machine to change the color of a display 
element temporarily. If the timeout value is not specified, the display element is changed to 
white for 30 seconds. If the state is not specified, the display element is changed to white 
for the specified timeout period; otherwise, the display element is changed to the color 
specified by the State parameter. 


The virtual G machine uses different colors to indicate a display element's state for the 
timeout period. When the time elapses and the window is redrawn, the element returns to 
its normal color. 


Note: To redraw the screen, call the set_element_mask function. 


Parameters 


ElementName Name of the display element to be highlighted. This parameter must be a 
string. 

TimeOut Specifies the period of time for the display element to be highlighted. This 
parameter must be an integer. 


State Specifies, through the use of color, the state of a display element. This 
parameter must be a string. Choose from the following states: 


Color Black-and-White Black-and-White 
hosts, node, links hosts and nodes links only 
up green white background solid line 
down red black background dotted line, large spaces 


unknown yellow shaded, white letters dotted line, finely spaced 
highlight white white background solid line 

acknowledge cyan (blue green) shaded, black letters thin, dashed line 

ignore violet shaded, black letters thin, dashed line 

inactive blue shaded, black letters thin, dashed line 





Return Values 
The function returns 0 if the element was defined, otherwise it returns —1. 
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Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The set_element_mask function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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hostname Function 


Purpose 
Returns the text name of the host. 
Syntax 
(string) hostname (/PAddress) 
int /PAddress; 
Description 
The hostname function returns the text name of the host. 
Parameter 
IPAddress Specifies the IP address of the specified host. This parameter must be an 
integer. 


Return Values 


The hostname function returns the name of the host. If the text name of the host cannot be 
determined, the IP address in dot notation is returned. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The dotaddr function, ipaddr function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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ipaddr Function 


Purpose 
Returns the normal, primary IP address of the specified host. 


Syntax 
(int) ipaddr (HostName) 
string HostName; 


Description 
The ipaddr function returns the normal, primary IP address of the host queried. 


Parameter 
HostName Specifies the name of the host to be queried. The HostName parameter 
may be specified as either the text name or the IP address in dotted decimal 
or dot notation (for example, 129.35.1.1). This parameter must be a 
string data type. 


Return Value 
Returns the binary 4—byte value of the IP address of the HostName parameter. 


Example 
1. The following is an example of the ipaddr function with a dotted decimal parameter: 


int re; 
roe = (int) ipaddr (7128.83 .1.35")> 
print "re is: td\n",re: 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The dotaddr function, hostname function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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left Function 


Purpose 
Extracts a substring beginning at the leftmost portion of the source string. 


Syntax 
(string) left (Source, Length) 


string Source; 
int Length; 


Description 
The left function returns a substring of a specified length that is extracted beginning at the 
leftmost portion of the source string. 


Parameters 
Source Specifies which string to use as source. This parameter must be a string 
data type. 


Length Specifies a number of characters to extract. This parameter must be an 
integer data type. 


Note: The index of the first character in the source string is always 1 (one). 
All strings in the xgmon programming utility are indexed this way. 


Return Value 
The left function returns a substring extracted from the left side of the source string. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The mid function, right function, strlen function, substr function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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lookup_addr Subroutine 


Purpose 
Returns the text name of a host. 
Syntax 
char *lookup_addr (address) 
unsigned long *address; 
Description 
_ The lookup_addr subroutine returns the text name of the host specified by the address 
parameter. 
Parameter 


address A pointer to the Internet address of the host. 


Return Value 
Returns the text name of the host specified by the address parameter. 


Implementation Specifics 


This subroutine is part of SNMP Appleton Programming Interface in AIX Network 
Management/6000. 


Related Information 
The SNMP_errormsg array. 


The lookup_host subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP) in Communications Programming Concepts. 
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lookup_host Subroutine 


Purpose 
Returns the Internet address of a host. 
Syntax 
unsigned long lookup_host (hostname) 
char *hostname; 
Description 
The lookup_host subroutine returns the Internet address associated with the host denoted 
by the hostname parameter. 
Parameter 


hostname Specifies the host for which the address is requested. The hostname 
parameter can be specified by using either the text name of the host (for 
example, localhost) or the name in dot notation (for example, 
127.0.0.1). If the hostname parameter is not specified in dot notation, the 
gethostbyname library routine is used to look up the host’s address. 


Return Values 
If the host is unknown, the lookup_host subroutine returns a 0 (zero). Otherwise, the return 
value is the Internet address of the named host. 


Implementation Specifics 
This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


Related Information 
The SNMP_errormsg array. 
The lookup_addr subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP) in Communications Programming Concepts. 
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lookup SNMP_group Subroutine 


Purpose 
Finds the set of all numeric-format variable names that contain a given text string as prefix. 
Syntax 
char **lookup_SNMP_group (prefix) 
char “prefix; 
Description 
The lookup_SNMP_group subroutine searches all text-format names in the /etc/mib_desc 
file and extracts those that are prefixed by the string given in the text parameter. The search 
is not case-sensitive. An array of pointers to the numeric~format names is returned. Each 
numeric—format name is terminated by a . (dot) so that an instance can be directly 
concatenated to it. 
Parameter 


prefix A pointer to a text string assumed to be the prefix of a group of MIB variable 
names in text format. 


Return Values 


If matching names are found, a pointer to an array of pointers to the matching names is | 


returned. The array is terminated by a pointer to an empty string. If no matching names are 
found, the array contains only the empty string pointer. 


Example 
1. The following entry returns a pointer to an array of four pointers: 


lookup_SNMP_group ("sys"); 


The first three pointers refer to the following character strings: 


MLeseOe le2 shel eke" 
WL gd Gsike2 « be dieda” 
WlesiOeleda ly tos” 


which are, respectively, "sysDescr”, "sysObjectId”, and "sysUpTime”. 
The fourth pointer (””) refers to an empty string. 


Note: A prefix value of "1.3.6” is invalid since the prefix parameter must not be 
numeric. 


Implementation Specifics 


This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


File 


/etc/mib_desc Defines the Management Information Base (MIB) variables. 
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Related Information 
The SNMP_errormsg array. 


The extract_SNMP_name subroutine, lookup_SNMP_name subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP), Understanding the Management Information Base (MIB), Understanding 
Terminology Related to Management Information Base (MIB) Variables, Working with 
Management Information Base (MIB) Variables in Communications Programming Concepts. 
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lookup SNMP_name Subroutine 


Purpose 
Returns the numeric—format name of a Management Information Base (MIB) variable. 
Syntax 
char *lookup_SNMP_name (text_name) 
char *text_name; 
Description 
The lookup_SNMP_name subroutine maps the text name of the MIB variable specified by 
the text_name parameter to the corresponding numeric-format name. This search is not 
case-sensitive. 
Parameter 


text_name Specifies the text name of the MIB variable. 


Return Values 
A pointer to the numeric—format name of the MIB variable specified by the text_name 
parameter is returned. If the text name is not recognized, a pointer to the null string is 


returned. Note that the returned name is terminated with a . (dot) so that an instance value 
can be directly concatenated to it. 


Example 
1. lf the text_name parameter is "sysDescr”, a pointer to the string 
Ere SeGale? 1s ids IS retumed. 


Note: A text name value of "1.3.6.1.2.1.1.1” is invalid since the text_name 
parameter must not be numeric. 


Implementation Specifics 


This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


File 


/etc/mib_desc Defines the Management Information Base (MIB) variables. 


Related Information 
The SNMP_errormsg array. 


The extract_SNMP_name subroutine, get_MIB_base_type subroutine, get_MIB_name 
subroutine, get_MIB_variable_type subroutine, lookup_SNMP_group subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP), Understanding the Management Information Base (MIB), Understanding 
Terminology Related to Management Information Base (MIB) Variables, Working with 
Management Information Base (MIB) Variables in Communications Programming Concepts. 
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make_dep Function 


Purpose 
Dynamically creates a new node or host. 


Syntax 
(int) make_dep (E/lementName) 
string ElementName; 


Description 
The make_dep function dynamically creates a new node or host in the topology display 
window. Before a node or host created by the make_dep function can appear in the 
topology display window, it must be mapped to the display by calling the group_dep 
function. 


If the new display element cannot be mapped to an IP address, the display element is 
treated as a node. If the display element does map to an IP address, the display element is 
treated as a host. 


Note: The display element names are treated case—insensitive; that is, a node or host 
named austin is the same node or host as the one named Austin. 


Parameter 
ElementName Indicates the name to be assigned to the new display element. This 
parameter must be a string data type. 


Return Values 


Returns a 0 (zero) if successful. Otherwise, —1 is returned. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The group_dep function, make_link function, move_dep function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 


Simple Network Management Protocol (SNMP) 6—47 


make_link 


make_link Function 


Purpose 
Dynamically creates a link between two hosts. 
Syntax 
(int) make_link (FromAddr, ToAddr) 
string FromAdar; 
string ToAdadr, 
Description 
The make_link function dynamically creates a link display element. 
Note: A node does not have an IP address and can therefore not be linked. 
Parameters 


FromAdar Specifies the host name or IP address from which the link extends. This 
parameter must be a string data type. 


ToAddr Specifies the host name or the IP address to which the link extends. This 
parameter must be a string data type. 


Return Values 
Returns an integer value as follows: 


0 (zero) The make_link function successfully created a link between two hosts. 

1 The host defined by the FromAdar parameter has an invalid IP address. 

2 The Fromadar parameter defines a node in the topology description file and 
has no interface. 

3 The host defined by the 7oAddr parameter has an invalid IP address. 

4 The ToAdar parameter defines a node in the topology description file and 


has no interface. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The make_dep function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 
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make SNMP_request Subroutine 


Purpose 
Encodes an SNMP request. 
Syntax 
int make_SNMP_request (req_type, community, num_vars, req_name, 
set_value, out_packet, max_outlen) 
int req_type; 
char *community; 
int num_vars; 
char *req_name{ J; 
unsigned long set_valuef ]; 
char *out_packet; 
int max_outlen; 
Description 
The make_SNMP_packet subroutine encodes a get, get-next, or set request. 
Parameters 
community Specifies a string that is the community name to be encoded in the packet. 
max_outlen Specifies the maximum length of the output buffer into which the encoded 
packet is placed. 
num_vars Specifies the number of variables to be requested or set. 
out_packet Points to a buffer in which the encoded packet is placed. 
req_name Specifies an array of pointers to the instance IDs on which an operation is 
performed. Each entry in the req_name array points to a string that 
represents a MIB instance ID in numeric format. 
req_type Specifies the request type, which can be one of the following: 
1 Indicates a get request. 
2 Indicates a get-next request. 
3 Indicates a set request. 
set_value Specifies an array of pointers or unsigned integers that correspond 


Return Values 


one-to-one with the instance IDs in the req_name array. Each entry is either 
the value of the corresponding instance ID if its base type is integer, or a 
pointer to the value if the base type is string. The set_va/ue parameter is 
used only with set requests. 


lf a fatal error occurs, —1 is returned. If the return value is non-negative, it represents the 
length of the generated packet. 
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Implementation Specifics 


This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


Related Information 
The SNMP_errormsg array. 
The parse_SNMP_packet subroutine, send_recv_SNMP_packet subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP), Understanding the Management Information Base (MIB), Understanding 
Terminology Related to Management Information Base (MIB) Variables, Working with 
Management Information Base (MIB) Variables in Communications Programming Concepts. 
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mid Function 


Purpose 
Extracts a substring from within the source string. 
Syntax 
(string) mid (Source, Start, Length) 
string Source; 
int Start; 
int Length; 
Description 
The mid function returns a substring of a specified length that is extracted from the source 
string beginning at the start position. 
Parameters 
Source Specifies which string to use as source. This parameter must be a string 
data type. 
Start Specifies the position of the first character extracted from the specified 
source string. This parameter must be an integer data type. 
Length Specifies a number of characters to extract. This parameter must be an 
integer data type. 


Note: The index of the first character in the source string is always 1 (one). 
All strings in the xgmon programming utility are indexed this way. 
For example, to specify the first character in the source string, set 
the Start parameter to 1. 


Return Value 
The mid function returns characters from the middle of the source string. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The ascii function, left function, right function, strlen function, substr function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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move_dep Function 


Purpose 
Changes the relative location of a display element within a topology display window. 


Syntax 


(int) move_dep (E/ementName, Intx, Int) 
string ElementName; 

int /ntx; 

int /nty; 


Description 
The move_dep function changes the relative location of a display element within a topology 


display window. The x and y coordinates are relative to the 100 x 100 reference grid used 
by the topology description utility. 


Note: Links cannot be moved. They are rooted to the hosts they connect. 


Parameters 


ElementName Specifies the name of the element to be moved. This parameter must 
be a string data type. 


Intx Specifies the position of the x coordinate. This parameter must be an 
integer data type. 


IntY Specifies the position of the y coordinate. This parameter must be an 
integer data type. 


Return Values 
If successful, the move_dep function returns a 0 (zero). Otherwise, —1 is returned. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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new_deps Function 


Purpose 
Returns a pointer to an array of strings representing the names of dynamically created 
display elements. 


Syntax 


(pointer) new_deps(0) 


Description 
The new_deps function returns a pointer to an array of strings representing the names of 
dynamically created display elements. The end of the list is marked by the null string. 


The list represents all of the display elements created by the xgmon program since the last 
call to the new_deps function. Note that the display elements created by the make_dep 
and make_link functions also appear in this list if they were created after the first display 
element was created by the xgmon program. 


Parameter 
Dummy parameter 0 (zero) is required. 


Return Value 


Returns a pointer to an array of strings representing the names of dynamically created 
display elements. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The make_dep function, make_link function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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next_alternate Function 


Purpose 
Changes the current primary address of the specified host to be the next available alternate 
address. 

Syntax 

(int) next_alternate (Hostname) 

string HostName; 
Description 

The next_alternate function changes the current primary address of the designated host to 

be the next available alternate address. Alternate addresses are selected in round-robin 

order. 

Note: Alternate addresses are specified in the topology description file. The designated 
host must have alternate addresses specified in the current topology description file; 
otherwise this command has no effect. 

Parameter 


HostName Specifies the name of the host to be queried. This parameter must be a 
string data type. 


Return Values | 
The next_alternate function returns 0 if the attempt fails, or 1 if it is successful. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The get_primary function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 


6-54 Base Operating System Reference. 


num 


num Function 


Purpose 
Returns a string of text characters representing the decimal value of the specified integer. 
Syntax 
(string) num (Number 
int Number, 
Description 
The num function returns the string of text characters that represent the decimal value of the 
Number parameter. The num function is the inverse of the val function. For various ways 
to format the string, refer to the sprintf function. 
Parameter 


Number The decimal value to be converted into a string of text characters. This 
parameter must be an integer. 


Return Value 


The num function returns the string of text characters that represent the decimal value of the 
Number parameter. 


implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The val function, sprintf function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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parse_SNMP_packet Subroutine 


Purpose 
Decodes an SNMP packet. 


Syntax 


int parse_SNMP_packet (packet, packet_len, from_host) 
char *packet; 

int packet_len; 

unsigned long from_host; 


Description 
The parse_SNMP_packet subroutine is called by the send_recv_SNMP_packet 
subroutine when an SNMP get-response packet is received. It may be called directly if an 
application receives packets directly. It extracts variable bindings from the packet and calls 


the save_SNMP_var or save_SNMP_trap subroutines as appropriate to process each 
binding in the packet. 


Parameters 
from_host Specifies the Internet address of the host sending the trap. 
packet Points to the contents of the packet. 
packet_len Specifies the packet length. 


Return Value 


If a fatal error occurs, a —1 is returned. If the return value is not non-negative, it is the error 
Status from the SNMP packet. A return value of 0 (zero) indicates no error. 


Implementation Specifics 


This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


Related Information 
The SNMP_errormsg array. 


The save_SNMP_var subroutine, save_SNMP_trap subroutine, send_recv_SNMP_packet 
subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP) in Communications Programming Concepts. 
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password Function 


Purpose 
Returns the SNMP community name associated with the specified host. 

Syntax 
(string) password (HostName) 
string HostName; 

Description 
The password function returns the SNMP community name associated with the specified 
host. This information is obtained from the current topology description. If there is no entry 
for the host, then the null string is returned. 

Parameter 


HostName Specifies the name of the host to be queried. This parameter must be a 
string data type. 


Return Values 
The password function returns the SNMP community name associated with the specified 
host in string format. If there is no entry for the host, the null string is returned. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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ping Function 


Purpose 
Sends an Internet Control Message Protocol (ICMP) ECHO request to the specified host. 
Syntax 
(int) ping (HostName) 
string HostName; 
Description ) 
The ping function sends an ICMP ECHO request to the named host. The HostName 
parameter can be either the host name or an IP address in dot notation. 
Parameter 


HostName Specifies the text name or IP address (in dot notation) of the host to be 
queried. This parameter must be a string data type. 


Return Values 


If a reply is not received, the return value is —1; otherwise, the return value is the number of 
milliseconds elapsed between the sending of the request and the arrival of the response. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The ping subcommand, ping_all subcommand. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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raise_window Function 


Purpose 
Raises the graphics window associated with the virtual G machine in which the program is 
running. 

Syntax 
(int) raise_window(0) 

Description 
The raise_window function attempts to raise the graphics window associated with the 
virtual G machine in which the program is running. 

Parameter 


Dummy parameter 0 (zero) is required. 


Return Values 


If no window is associated with the virtual G machine, —1 is returned. If successful, the 
raise_window function returns 0 (zero). 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 


Simple Network Management Protocol (SNMP) 6—59 


read | 





read Function 


Purpose 
Reads the next line in an open file specified by the file descriptor. 

Syntax 
(string) read (FileDescripton 
int FileDescriptor, 

Description 
The read function returns the next line in the open file indicated by the FileDescriptor 
parameter. When it reaches end—of-file, this routine returns the null string. The read 
function always adds a trailing space to the actual data. 

Parameter 


FileDescriptor File descriptor. This parameter must be an integer. 


Return Value 
The line of text string read from the file. 


Example 
1. int fd; 
string s; 
fd = (int) fopen (filename, "r"); 
if (fd !=0) 
s=(string)read(fd); 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The fopen function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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real _type Function 


Purpose 
Takes a Management Information Base (MIB) numeric—format variable name or 
numeric—format instance ID and returns a number indicating its actual MIB type. 
Syntax 
(int) real_type (ObjectiD) 
string ObjectiD; 
Description 
The real_type function takes an MIB numeric—format variable name or numeric—format 
instance ID and returns a number indicating its actual MIB type. 
Parameter 


ObjectID Specifies the numeric—format variable name or numeric—format instance ID 
of the MIB object whose MIB type is queried. This parameter must be a 
string data type. 


Return Values 
Returns an integer designating the MIB type as follows: 


1 = number 

2 = String 

3 = object ID 
4 = empty 

5 = IP address 
6 = counter 

7 = gauge 

8 = time ticks. 


lf the MIB type cannot be determined, —1 is returned. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Understanding the Simple Network Management Protocol! (SNMP), Understanding the 
Management Information Base (MIB), Understanding Terminology Related to Management 
Information Base (MIB) Variables, Working with Management Information Base (MIB) 
Variables in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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rename_dep Function 


Purpose 
Renames a display element. 

Syntax 
(int) rename_dep (E/ementName, NewName) 
string ElementName; 
string NewName; 

Description | 
The rename_dep function renames a display element. The new name must map to the 
same IP address as the original. This means that the new name and IP address must be in 
the /etc/hosts file or the auxiliary host file. Remember to execute the clearcache system 
command when these files are altered. 

Parameters 


ElementName Specifies the name of the display element to be renamed. This 
parameter must be a string data type. 


NewName Specifies the new name of the display element. This parameter must 
be a string data type. 


Return Values 
If successful, the rename_dep function returns 0 (zero). Otherwise, it returns —1. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The clearcache system command, hostdata system command. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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reuse_mem Function 


Purpose 
Controls garbage collection by a virtual G machine (VGM). 

Syntax 
(int) reuse_mem(EnableFiag) 
int EnableFlag; 

Description 
The reuse_mem function is used by a VGM to control garbage collection. By default, 
garbage collection is not enabled. If the reuse_mem function is called with a nonzero 
argument, an attempt to enable garbage collection is made. This may not be successful 
because the operator has the ability to disable garbage collection by using the reuse system 
command. 

Parameter 


EnableFlag This parameter is set to a nonzero value to enable garbage collection. 


Return Values . 
Returns a 1 if garbage collection is enabled. Otherwise, a 0 (zero) is returned. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The reuse system command. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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right Function 


Purpose 
Extracts a substring from the rightmost portion of the source string. 
Syntax 
(string) right (Source, Length) 
string Source; 
int Length; 
Description 
The right function returns a substring of a specified length that is extracted from the 
rightmost portion of the source string. 
Parameters 
Source Specifies which string to use as source. This parameter must be a string 
data type. 
Length Specifies a number of characters to extract. This parameter must be an 
integer data type. 


Note: The index of the first character in the source string is always 1 (one). 
All strings in the xgmon programming utility are indexed this way. 


Return Value | 
The right function returns a substring extracted from the right side of the source string. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The left function, mid function, strlen function, substr function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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save _SNMP_trap Subroutine 


Purpose 
Stores SNMP trap data. 
Syntax 
void save_SNMP_trap (enterprise, address, generic, specific, time_stamp) 
char *enterprise; 
unsigned long address; 
char *generic; 
char *specific; 
unsigned long time_stamp; 
Description 
The save_SNMP_trap subroutine is called by the parse_SNMP_packet subroutine when a 
trap packet is parsed. This routine prints the obtained values on the standard output in the 
following format: 
"trap received from [enterprise] address: (generic, specific) time 
stamp = time_stamp” 
Parameters 
enterprise Specifies the value of the sysObjectID MIB variable of the agent generating 
the trap. This MIB variable is explained in RFC 1066. 
address Specifies the Internet address of the host generating the trap. 
generic Specifies the generic trap type. The string is the text representation of the 


number associated with the trap type. For example, the number 0 
corresponds to a cold-start trap, and the number 2 corresponds to a 
link-down trap. 


specitic Specifies a particular instance of a trap identified by a user. For the link-up 
and link-down traps, the value specified by the specific parameter indicates 
the interface number associated with the trap. For EGP neighbor-loss trap, 
specific indicates the address of the neighbor in dot notation. 


time_stamp Specifies the time stamp associated with the trap. The time stamp 
represents the number of 100ths of seconds passed since the agent was 
initialized at the time the trap was regenerated. 


Note: The generic and specific parameters point to space on the stack; this space is 
reclaimed when the save_SNMP_trap subroutine returns. The enterprise parameter 
points to a static data area which will be overwritten after the save_SNMP_trap 
returns. 


Implementation Specifics 


This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


Simple Network Management Protocol (SNMP) 6-65 


save SNMP _trap 


Related Information 
The SNMP_errormsg array. 


The parse_SNMP_packet subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP) in Communications Programming Concepts. 
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save_SNMP_var Subroutine 


Purpose 
Stores retrieved SNMP variable data. 
Syntax 
void save_SNMP_var (from_host, var_name, real_type, base_type, result, len) 
unsigned long from_host; 
char *var_name; 
int real_type; 
int base_type; 
union_var_val result; 
int /en; 
Description 
The save_SNMP_var subroutine is called by the parse_SNMP_packet subroutine when a 
get-response packet is parsed. The default routine prints the obtained values on the 
standard output in the format of either var_name = string value or var_name = integer value. 
The save_SNMP_var subroutine does not manipulate the retrieved data. 
Parameters 
base_type Specifies the base type of the object. A value of 1 indicates that the object 
is a string. A value of 2 indicates that the object is an unsigned long integer. 
from_host Specifies the Internet address of the host generating the trap. 
len The size of the integer specified by the base type, or the length of the string 


specified by the base type. 


If the value specified by the base_type parameter is a string, the value of 
the /en parameter does not include the trailing null byte. 


If the value specified by the base_type parameter is an integer, the /en 
parameter has the value of 0 (zero) in special cases of empty objects. 


real_type Specifies the variable type as defined in RFC 1066. 


The values for the real_type parameter are: 


1 number 

2 octet string 

3 object identifier 
4 empty 

5 Internet address 
6 counter 

7 gauge 

8 time ticks. 
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result Specifies the value of the variable. It has the following format: 
union _var_val { 
unsigned long ul; 
char *cp; 
}3 
var_name Specifies the variable name in numeric format. 


Note: If the base type of the object is a string (that is, base_type = 1), then the storage 
pointed to by the var_name and result parameters is reclaimed by the operating 
system when the save_SNMP_var subroutine returns. 


Implementation Specifics 


This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


Related Information 
The SNMP_errormsg array. 


The parse_SNMP_packet subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP) in Communications Programming Concepts. 


6-68 Base Operating System Reference 


send_recv_SNMP_packet 


send_recv_SNMP_packet Subroutine 


Purpose 
Sends a query to and awaits a response from an SNMP agent. 


Syntax 


int send_recv_SNMP_packet (fd, dest, out_packet, packet_len) 
int fd; 

struct sockaddr_in *dest; 

char *out_packet, 

int packet_len; 


Description 
The send_recv_SNMP_packet subroutine can be used to send an SNMP request to an 
SNMP agent, await a response, and process the response packet. 
The routine sends the packet to the destination specified by the dest parameter. 


lf a response is obtained from the SNMP agent, then the parse_SNMP_packet subroutine 
will be called with the contents of the received response packet. 


Parameters 


dest Specifies the destination address to which the SNMP request is sent. The 


dest parameter can be the dest_host external variable set by the 
create_SNMP_port subroutine. 


fd Describes a socket used for the sendto and recvfrom I/O subroutines. The 


fd parameter can be the address of the SNMP_port external variable set by 
the create_SNMP_port subroutine. 


out_packet Contains the SNMP request to be sent. 


packet_len Length of the data specified by the out_packet parameter. 


External Variables 
max_SNMP_retries 


Determines the maximum number of times to retry a request. The default 
value is 3. 


SNMP_timeout Determines the time to wait for a response to be received. The default 
value is 5 seconds. 


The values of these external variables can be reset in the user’s main( ) initialization code if 
necessary. 


Return Values 
If the agent does not respond, or if an !/O error occurs, —1 is returned; otherwise, the SNMP 


error status from the response packet is returned. An SNMP error status of 0 indicates no 
error. 
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implementation Specifics 


This subroutine is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


Related Information 
The SNMP_errormsg array. 


The create_SNMP_port subroutine, parse_SNMP_packet subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP) in Communications Programming Concepts. 
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set_element_mask Function 


Purpose 


Allows a virtual G machine to change the current display element mask. 


Syntax 


(int) set_element_mask (New Mask) 
int NewMask; 


Description 


The element_mask global variable controls how the display elements are drawn. The 
set_element_mask function allows a virtual G machine to change the current mask and 
returns the value of the o/d mask. The function also controls whether or not the bell sounds 
and whether the bell sound is double or two-tone. 


The mask element starts at the low-order bit 0 (zero) and controls several types of objects. 
When one of the following bits is specified, the set_element_mask function causes the bit’s 
corresponding object to be drawn on the screen: 


Bit 
0 
1 


oO oa WO 


10 


Object 


reserved 

hosts 

nodes 

logical links 

physical links 

bell; double alert if bit 10 is not set 


two-tone alert. 


Note: The set_element_mask function always causes the visible topology window to be 


Parameter 


NewMask 


Return Value 


redrawn, even if the mask has not been changed. 


Specifies the display element mask to be changed. This parameter must be 
an integer. 


The set_element_mask function returns the value of the new mask and expresses it as an 


integer. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Simple Network Management Protocol (SNMP) 6-71 


set_element_mask 


Related Information 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create | 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 


Programming Concepts. 
Using Intrinsic Functions in Communications Programming Concepts. 


Working with Virtual G Machine (VGM) Variables in Communications Programming 
Concepts. 
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setenv Function 


Purpose 


Syntax 


Sets the user-defined environment variable for a host to the specified value. 


(int) setenv (DisplayElementName, VariableName, Value) 
string DisplayElementName; 

string VariableName; 

string Value; 


Description 


The setenv function sets the user-defined environment variables associated with a display 
element to the specified value. The xgmon program recognizes the RIGHTCLICK 
environment variable name as being associated with the name of the library command that 
should be run when the display element is double—clicked with the right mouse button. 


Parameters 


DisplayElementName 
Specifies the name or IP address (in dot notation) of the display element for 
which an environment variable is to be set. This parameter must be a string 
data type. 


Variable Specifies the name of the user-defined environment variable to be set. This 
parameter must be a string data type. 


Value Specifies the value to which the user-defined environment variable will be 
set. This parameter must be a string data type. 


Examples of environment variables and values defined by the user are as follows: 


OS IBM AIX Version 3.1 
owner Gideon Kim 
name Token—Ring LAN 


Return Values 


The return code is 0 (zero) if the setenv function is successful; otherwise, —1 is returned. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 
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Related Information | 
The getenv subcommand, setenv subcommand, load_env subcommand. 


The getenv intrinsic function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions Communications Programming Concepts. 


Using Intrinsic FunctionsCommunications Programming Concepts. 
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SNMP_errormsg Array 


Purpose 

Stores SNMP error messages. 
Syntax 

char *SNMP_errormsg[ ]; 
Description 


The SNMP_errormsg array is an array of pointers to strings containing the appropriate 
English text corresponding to each SNMP error status value returned by the 
send_recv_SNMP_packet subroutine as follows: 


Index Contents 

0 No error 

1 Too big 

2 No such name 

3 Bad value 

4 Read only. 

5 Unsupported or unauthorized operation. 


Implementation Specifics 
This array is part of SNMP Application Programming Interface in AIX Network 
Management/6000. 


Related Information 
The send_recv_SNMP_packet subroutine. 


Using the SNMP API Subroutine Library, Understanding the Simple Network Management 
Protocol (SNMP) in Communications Programming Concepts. 
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snmp_var Function 


Purpose 
Returns the Management Information Base (MIB) numeric—format variable name associated 
with a specified MIB text-format variable name. 


Syntax 


(string) snmp_var ( VariableName) 
string VariableName; 


Description 
The snmp_var function returns the MIB numeric—format variable name associated with the 
VariableName parameter. The returned string always has a trailing . (dot). If no such MIB 
text-format variable name is known, the null string is returned. The MIB text-format variable 
name and MIB numeric—format variable name mappings are obtained from the mib_desc 
file. 


Parameter 
VariableName Specifies the MIB text-format variable name for which the MIB 


numeric—format variable name is queried. This parameter must be a 
string data type. 


Return Value 
Returns the MIB numeric—format variable name associated with the Simple Network 
Management Protocol (SNMP) variable in string format. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


File 
/etc/mib/_desc Defines the Management Information Base (MIB) variables that the 


xgmon program should recognize and handle. The user also specifies 
a time-to-live (TTL) value (in seconds) for each variable. 


Related Information 
Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Understanding the Simple Network Management Protocol (SNMP), Understanding the 
Management Information Base (MIB), Understanding Terminology Related to Management 
Information Base (MIB) Variables, Working with Management Information Base (MIB) 
Variables in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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sprintf Function 


Purpose 
Enables formatted arguments. 


Syntax 


(string) sprintf (Format,. Argument1, Argumeniz...) 
string Format; 
DataType Argument; 


Description 
The sprintf function provides various ways to format arguments. 


Parameters 
Format A string specifying the format requirements. 
Argument1, Argumeniz... These parameters can be integers, strings, or pointers. 


Return Value 
The sprintf intrinsic function returns a formatted string. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The sprintf function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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strlen Function 


Purpose 
Returns the length of a string. 
Syntax 
(int) strlen (String) 
string String; 
Description 
The strlen function returns the length of the string specified by the String parameter. 
Parameter 
String Specifies the string to be queried. This parameter must be a string data 
type. 


Return Value 
The strlen function returns the length of the string. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The left function, mid function, right function, substr function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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substr Function 


Purpose 
Searches a source string for a particular substring and returns the position of the leftmost 
occurrence of that substring. 


Syntax 


(int) substr (Source, Target) 
string Source; 
string Target; 


Description 
The substr function searches the string specified by the Source parameter for a string 


specified by the Target parameter. Once the target string is located, the substr function 
returns the position of the leftmost occurrence of the Target string. 


Note: The index of the first character in the source string is always 1 (one). All strings in 
the xgmon programming utility are indexed this way. 


Parameters 
Source Specifies the name of the source string to be queried. This parameter must 
be a string data type. 


Target Specifies the name of the target string to be queried. This parameter must 
be a string data type. 


Return Values 


If the Target string does not appear in the Source string, 0 is returned. Otherwise, the 
position of the leftmost occurrence of the Target string is returned. 


Implementation Specifics 
This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The left function, mid function, right function, strlen function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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time Function 


Purpose 
Returns the current system time. 


Syntax 
(int) time(0) 


Description 
The time function returns the current system time and expresses it in seconds. 


Parameter 
Dummy parameter 0 (zero) is required. 


Return Value | 
The time function returns the current system time and expresses it in seconds. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The ctime function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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val Function 


Purpose 
Returns the integer value represented by the text characters in the specified string. 
Syntax 
(int) val (NumberString) 
string NumberString; 
Description 
The val function returns the integer value represented by the text characters in the specified 
string. It assumes the number is to be interpreted as a decimal number. 
Note: See the atoi subroutine for details. 
Parameter 
NumberString Specifies the number string to be queried. This parameter must be a 
string data type. 


Return Value 


The val function returns the integer value represented by the text characters in the specified 
string. 


implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The hexval function, num function. 
The atoi subroutine. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions in Communications Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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window_ height Function 


Purpose 
Returns the height, in pixels, of the graphics window associated with a virtual G machine. 


Syntax 
int window_height(0) 


Description 


The window_height function returns the height, in pixels, of the graphics window 
associated with the virtual G machine in which the program is running. 


Parameter 
Dummy parameter 0 (zero) is required. 


Return Values 


Returns the height, in pixels, of the graphics window associated with the virtual G machine in 


which the program is running. If there is no window associated with the virtual G machine, 
—1 is returned. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The window_width function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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window_width Function 


Purpose 
Returns the width, in pixels, of the graphics window associated with a virtual G machine. 


Syntax 
(int) window_width(0) 


Description 
The window_width function returns the width, in pixels, of the graphics window associated 
with the virtual G machine in which the program is running. 


Parameter 
Dummy parameter 0 (zero) is required. 


Return Values 
Returns the width, in pixels, of the graphics window associated with the virtual G machine in 


which the program is running. If there is no window associated with the virtual G machine, 
—1 is returned. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 
The window_height function. 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 
xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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words free Function 


Purpose 
Returns the number of free words remaining in the data segment of the virtual G machine. 
Syntax 
(int) words_free(0) 
Description 
The words free function returns the amount of free space available in the data segment of 
the virtual G machine. This storage space is measured in units of 32 bits. These units are 
also referred to as words. 
Note: Ifa virtual G machine attempts to use more storage than allocated in its data 
segment, it is stopped. 
Parameter 


Dummy parameter 0 (zero). This parameter is required. 


Return Value 


Returns the number of free storage units (32-bit words) remaining in the data segment of 
the virtual G machine. 


Implementation Specifics 


This intrinsic function is part of Simple Network Management Protocol (SNMP) Manager in 
AIX Network Management/6000. 


Related Information 


Alphabetic List of Intrinsic Functions, Functional List of Intrinsic Functions, How to Create 


xgmon Intrinsic Functions, How to Create xgmon Library Commands in Communications 
Programming Concepts. 


Using Intrinsic Functions in Communications Programming Concepts. 
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close 


close Subroutine for SNA Services/6000 


Purpose 

Closes a file descriptor. 
Syntax 

#include <luxsna.h> 

int close( fides) 

int fildes; 
Description 


The close subroutine closes a connection specified by its file descriptor. 


Limited Interface 
If the file descriptor was opened using the limited interface, this routine also deallocates the 


conversation associated with the file descriptor, using the following parameters (see the 
ioctl(DEALLOCATE) subroutine): 


e The type parameter has a value of FLUSH (DEAL_FLUSH) 
e The deal_flag parameter is DISCARD. 


Extended Interface 
If the file descriptor was opened using the extended interface, any active conversations on 
the connection end abnormally. 


Parameter 


fildes Specifies a variable containing the file descriptor of the connection to be 


closed. This file descriptor is the value returned by the open subroutine that 
opened the connection. 


Return Values 
When the subroutine completes successfully, it returns a value of 0. If an error occurs, the 
routine returns a value of —1 and sets the errno global variable to indicate the error. 


Error Code 
The close subroutine sets the errno global variable to a value to indicate the cause of any 
errors that occur. The value that this variable can receive is shown below. Error Code 
Constants in Communications Programming Concepts contains a brief description of the 
error values for AIX SNA Services/6000. 


EBADF 
File 


/usr/include/luxsna.h 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 
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Related Information 
The close subroutine. 


The open subroutine for SNA Services/6000, ioct! subroutine for SNA Services/6000, 
snaclse subroutine for SNA Services/6000. 
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close Subroutine for Generic SNA 


Purpose 
Closes a file descriptor. 


Syntax 


#include <luxgsna.h> 


int close (fildes, ext) 
int fildes; 
int ext, 


Description 


The close subroutine releases resources that are tied to an AIX SNA Services/6000 
attachment specified by its file descriptor. 


Parameters 
fildes Specifies a variable containing the file descriptor to be closed. This file 
descriptor is the value returned by the open subroutine. 


ext Ignored by generic SNA. 


Return Values 


Upon successful completion, the close subroutine returns a value of 0. If an error occurs, it 
returns a value of —1 and sets errno to indicate the error. 


Error Code 


The call sets errno to a value which indicates the cause of any errors that occur, as in the 
following case: 


EBADF An invalid file descriptor was specified. 


Related Information 


The open Subroutine for Generic SNA, read Subroutine for Generic SNA, write Subroutine 
for Generic SNA, ioctl Subroutine for Generic SNA, select Subroutine for Generic SNA. 


Developing Special AIX SNA Services/6000 Functions in Communications Programming 
Concepts. 
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ioctl Subroutine for SNA Services/6000 


Purpose 


Syntax 


Controls data transfer between local and remote transaction programs. 


#include <luxsna.h> 


int ioctl(fd, request, arg) 
int fd; 

int request; 

int arg; 


Description 


ALLOCATE 


Note: Do not use this subroutine for programs that use the limited interface. 


This subroutine provides control functions for transfer operations between a local and a 
remote transaction program. The specific control function is specified by the request 
parameter and must be one of the integers (defined in the luxsna.h include file) as 
explained in the following sections: 


e ALLOCATE 

e ALLOCATE_LISTEN (LU 6.2 only) 

e CONFIRM 

e CONFIRMED 

e CP_STATUS (LU 6.2 only) 

e DEALLOCATE 

e FLUSH 

e GET_ATTRIBUTE (LU 6.2 only) 

e GET_PARAMETERS (LU 6.2 only) 

e GET_STATUS (LUs 1, 2, and 3 only). 
e PREPARE_TO_RECEIVE 

e REQUEST_TO SEND 

e SEND_ERROR 

e SEND_FMH (LU 1 only) 

e SEND_STATUS (LUs 1, 2, and 3 only). 


The ALLOCATE request allocates a session between the local logical unit or control point 
(LU/CP) and a remote LU/CP. It then allocates a conversation between the local transaction 
program and a remote transaction program using the allocated session. The request returns 
a resource ID to identify the conversation. Use this request before using any other 
subroutine that refers to the conversation. 
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If two LUs, connected by a session, try to allocate a conversation on that session at the 
same time, one of the LUs will be successful and the other will not. Which LU is successful 
is determined by the BIND negotiation that occurred when the session was established. 


The arg parameter is a pointer to a structure of type allo_str that contains additional 
information for the request. This structure contains a pointer to an additional structure, 
pip_str. These structures are defined in the luxsna.h include file. The resource ID (RID) is 
returned in the extended allocate structure. Refer to the allo_str and pip_str structures for 
information about the fields in these structures. 


You must ensure that the remote transaction program name (tpn) is in EBCDIC coding 
before it is stored in the allo_str structure. Refer to EBCDIC to ASCIi Translation for US 
English (TEXT)Communication Concepts and Procedures for assistance in converting ASCII 
to EBCDIC. 


LU 6.2 


When this request completes successfully, the local transaction program (the one that used 
this request) is in the send state and the remote transaction program is in the receive state. 


For two programs to reconnect to each other after they have been disconnected, the 
following events must occur: 


1. One program uses a DEALLOCATE request with the deal_ flag parameter set to 
retain to deallocate the conversation. 


2. The program initiating the reconnection uses an ALLOCATE request with the type 
parameter set to reconnect. This action sends a reconnection request to the remote 
LU. 


3. The remote program completes the reconnection when it uses the read or readx 
subroutines to receive information. 


4. If the application program is performing a remotely attached ALLOCATE request or 
reconnection, the program must specify the resource ID, rid, in the allo_str structure. 


LUs 1, 2, and 3 


When this request completes successfully, the appropriate session (SSCP—LU or LU—LV) is 
established and both LUs are in HDX contention state. The SSCP-LU session must be 
active and allocated before allocating the LU-LU session. Trying to allocate the LU-LU 
session before the SSCP-LU session results ina SNA_STATE error return from the 
ALLOCATE request. 


If an application program tries to allocate an SSCP-LU session and the ACTLU request has 
not yet been received: 


e This subroutine returns a SNA_NSES error. 
e When the ACTLU request arrives, the logical unit (LU) starts. 


Note: Ifa NOTIFY signal is not supported by the host system, the ACTLU request is 
always accepted with a +RSP (SLU-—enabled) ACTLU. If a NOTIFY signal is 
supported by the host system, the ACTLU request is accepted with a +RSP 
(SLU—enabled) if an ALLOCATE SSCP request was previously attempted or with 
a +RSP (SLU-disabled) if an ALLOCATE SSCP request has not yet been 
attempted. 


e A+RSP ACTLU (SLU-enabled) request is sent. 
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e The select subroutine notifies the application program of a change in status. 
e The GET_STATUS request indicates that the SSCP is active. 
e The application program allocates the SSCP-—LU session. 


If an application program tries to allocate an SSCP—LU session after the ACTLU request is 
received: 


e Ifa NOTIFY signal is supported by the Host system and an ACTLU (SLU-disabled) signal 
was accepted, a NOTIFY (SLU-—enabled) signal is sent to the Host system. 


e Asession is allocated. 


If an application program tries to allocate an LU-LU session and the BIND request has not 
yet been received: 


e The ioctl subroutine puts the application to sleep waiting for the BIND request to be 
received and processed. 


e An INIT_SELF request is sent to the Host system to request the BIND request. 
e When the BIND request arrives, the logical unit (LU) starts. 

¢ A+RSP BIND is sent. | | 

e The LU-LU session is allocated to the application program. 


If an application program tries to allocate an LU-LU session after the BIND request is 
received: 


e Asession is allocated. 


If the host bids for a session, a subsequent ALLOCATE causes sense code 0x0813 (Host 
bid reject). The bid can be either sent with the Begin Bracket (BB) bit on or a BID command. 


ALLOCATE_LISTEN 


CONFIRM 
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The ALLOCATE_LISTEN request registers a list or Transaction Program Names (TPNs) for 
which an application wishes to accept allocate requests (for example, FMH5 Attaches). 
When an allocate request is received by SNA for one of the registered TPNs, the application 
will be informed via the select(EXCEPTION) subroutine. This routine may be issued multiple 
time on any connection. Each successive call registers another set of TPNs on that 
connection. The ALLOCATE_LISTEN request can be used by LU 6.2 only. 


The CONFIRM request asks the remote transaction program to tell whether the last 
transmission was successfully received. The remote transaction program must respond with 
one of two ioctl subroutine requests: CONFIRMED or SEND_ERROR. 


The filedes for this request is the connection ID (cid) returned from a previous open 
routine. 


For this request, the arg parameter is a pointer to a structure of type confirm_st. The 
resource ID (rid) that was returned on a previous ALLOCATE must be passed in the 
confirm_str structure. Information about the conversation is returned in the sense_code 
field of the confirm_str structure. This structure is defined in the luxsna.h include file. Refer 
to the confirm_str structure for information about the fields in this structure. 


Base Operating System Reference 


ioctl 


LU 6.2 
The program may use the CONFIRM request for the following special cases: 


e Immediately following an ioctl(ALLOCATE) request to determine if the allocation of the 
conversation was successful before sending data 


e Following transmission of data to the remote program to get an acknowledgment from the 
remote program. 


LUs 1, 2, and 3 


LU 1 uses the CONFIRM request to get an acknowledgment for data that the LU sent to the 
remote program. However, LUs 2 and 3 do not use this request. The remote program must 
handle error recovery for the local LU 2 or 3 program. 


CONFIRMED 


CP_STATUS 


The CONFIRMED request is a response to the CONFIRM request indicating that the 
transmission was received without detecting any errors. This request can only be used in 
response to a CONFIRM request. 


The filedes for this request is the connection ID (cid) returned from a previous open 
routine. 


For this request, the arg parameter is the resource ID (rid) that was returned on a previous 
ALLOCATE request. 


CP_STATUS requests information about the capabilities of the control point at the remote 
node. 


The filedes for this request is the connection ID (cid) returned from a previous open 
routine. 


For this request, the arg parameter is a pointer to a structure of type cp_str. The resource 
ID (rid) that was returned on a previous ALLOCATE request must be passed in the cp_str 
structure. The remote control point name, the conversation group0 ID, and the session type 
(contention winner or contention loser) are returned by the ioctl subroutine in the cp_str 
structure pointed to by the arg parameter. This subroutine also returns a list of remote CP 
Capabilities in the cp_str structure as defined in the luxsna.h include file. Refer to the 
cp_str structure for a description of the fields in this structure. 


DEALLOCATE 


The DEALLOCATE request deallocates the specified conversation from the local transaction 
program and makes the conversation available to be allocated by another transaction 
program. Information about the specific type of DEALLOCATE request is supplied in the 
deal_str structure pointed to by the arg parameter. 


The filedes for this request is the connection ID (cid) returned from a previous open 
routine. 


For this request, the arg parameter is a pointer to a structure of type deal_str. The resource 
ID (rid) that was returned on a previous ALLOCATE must be passed in the deal_ str 
structure. The transaction program should specify the type of deallocate to be preformed 
(DEFAULT, CONFIRM, ABEND, or FLUSH) in the type field of the deal_str structure. The 
transaction program should also specify whether the conversation should be discarded or 
retained for possible reconnection in the deal_ flag field of the deal_str structure. 
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This structure is defined in the luxsna.h include file. Refer to the deal_str structure for 
information about the fields in this structure. 


LU 6.2 


The DEALLOCATE request ends the conversation but not the session. The LU resource 
manager determines whether to keep or end the session. The DEALLOCATE request is only 
issued by a local transaction program. A remote transaction program receives an indication 
that a DEALLOCATE request was received from the SNA device driver. The device driver 
sets the what_control_rcvd field in the ext_io_str structure to indicate the type of 
deallocation the device driver received from the remote program. 


The remote transaction program must take appropriate action based on the type of 
DEALLOCATE request received. For example, for deallocate type CONFIRM, the remote 
transaction program issues the ioctl(CONFIRMED) subroutine to complete the deallocation 
sequence. The remote transaction program is not required to issue a DEALLOCATE request 
in response to a received DEALLOCATE. 


See the readx subroutine for an explanation of the ext_io_str structure. The SNA device 
driver performs the local deallocation function when it receives a DEALLOCATE request 
from the remote transaction program. 


LUs 1, 2, and 3 


Do not use the DEALLOCATE request with an LU-LU session for either LUs 2 or 3. If used 
with these sessions, the routine returns with an SNA_STATE error. 


To deallocate an LU-LU session that has a corresponding SSCP-—LU session, use the 
DEALLOCATE request to deallocate the SSCP-—LU session. 


When the local transaction program issues a DEALLOCATE request with type set to 
(DEAL_FLUSH) for the SSCP-LU session: 


1. An RSHUTD is sent to the host requesting that the host issue an UNBIND request to 
terminate the LU-LU session. 


2. The local LU rejects all data from the host on the LU-LU session until it receives the 
UNBIND request. 


3. If the host supports a NOTIFY signal, a NOTIFY (SLU_DISABLED) signal is sent to the 
SSCP. 


4. The next allocation of SSCP causes a NOTIFY (SLU_enabled) signal. 


5. The local LU rejects all data from the host on the SSCP-LU session until that session is 
allocated to another application program. 


The host can issue an UNBIND request at other times to end the LU-LU session. When the 
UNBIND occurs, the local program using the LU-LU session receives a return code of 
SNA_NSES to notify it of the session end. 


Unless an RSHUTD is sent, all UNBIND requests are unsolicited. The SNA_NSES signal is 
returned by SNA_DD (for the read subroutine, the write subroutine, and so on). The 
SELECT is completed, if there is one pending. When an unsolicited UNBIND request occurs, 
the local LU ends the session and uses the select subroutine to notify the application 
program using the session. The select subroutine will complete with an exceptional 
condition. If the application uses a GET_STATUS request of the ioctl subroutine, the 
returned status indicates that the session is not active. 
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The local LU cannot issue a DACTLU request to end the SSCP-—LU session. Therefore, the 
session remains active until the host ends it with a DACTLU, DACTPU or ACTPU request. In 
this case, the DEALLOCATE request used on the SSCP-LU session removes the 
connection to the local program, but does not remove the SSCP-LU session itself. 


When used on an LU 1 LU-LU session, the DEALLOCATE request ends a bracket. 


FLUSH 
The FLUSH request sends any information in the local LU send buffer to the remote LU. The 
LU normally buffers the data from write subroutines until it has enough data to transmit. 
Using this request the local program forces the local LU to transmit the data in the buffer. 
The local program can use this request to decrease the delay required to get the data to the 
remote system. If you use this request when the local transmit buffer is empty, the local LU 
transmits a null chain element to the remote LU if end chain is specified. 


The arg parameter for this request is a pointer to a structure of type flush_str, which 
contains the input parameters for the request. For LU 6.2, the end_chain field in the 
flush_str structure should always be set to a value of 0. Refer to the flush_str structure for 
a description of the fields in this structure. 


GET_ATTRIBUTE 
The GET_ATTRIBUTE request gets information about the specified LU 6.2 conversation. 


The arg parameter for this request is a pointer to a structure of type attr_str which contains 
the input parameter rid and receives the output information from the request. Refer to the 
attr_str structure for a description of the fields in this structure. 


GET_PARAMETERS 
The GET_PARAMETERS request retrieves the data associated with the receipt of an 
allocate request (for example, FMH5 Attach) for a registered TPN on a particular connection. 
The data that is returned is for the first allocate request received since the last 
GET_PARAMETERS call was issued. The GET_PARAMETERS request can be used by LU 
6.2 only. 


GET STATUS 
The GET_STATUS request gets information about the current link and session, as well as 


the unprocessed image from the BIND request for the LU-LU session. It can be used by 
LUs 1, 2, and 3 only. 


When an event occurs that changes the status of a link or session, the system informs the 
application program, using the select subroutine. If the application program then uses 
GET_STATUS, the status returned is for the session that was affected by the change in 
status. For example, when a BIND request and an SDT request are received, the system 
uses the select subroutine to notify the application program of the change. When the 
application uses GET_STATUS, the returned status indicates that the LU-LU session is 
active. 


The arg parameter for this request is a pointer to a structure of type gstat_str, which 
contains the input parameter rid and receives the output status information from the 
request. Refer to the gstat_str structure for a description of the fields in this structure. 


Because GET_STATUS reports status changes, gstat_str can have a status value of 0. 
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PREPARE TO RECEIVE 


The PREPARE_TO_RECEIVE request notifies the remote LU that the local LU needs to 


change the conversation direction so that the local LU can begin receiving from the remote 
LU. 


The arg parameter for this request is a pointer to a structure of type prep_str which contains 
the input parameters for the request. Refer to the prep_str structure for a description of the 
fields in this structure. 


Special Cases 


Transaction programs can use this request with a type field of FLUSH to complete a write 
subroutine and send a change-of-direction (CD) indication to the remote transaction 
program. If the send buffer is empty, the request sends a Null FMD with a CD to the remote 
transaction program. 


Transaction programs also use this request with a type field of CONFIRM to complete a 
write subroutine. In this case, the request sends the CD indication with a Request 
Definite Response message. 


REQUEST _TO_ SEND 


The REQUEST_TO_SEND request notifies the remote LU that the local LU needs to change 
the conversation direction so that the local LU can begin sending to the remote LU. The local 
program uses a readx subroutine to get the send indication from the remote program (in the 
what_control_rcvd field). When the local program receives this indication from the 
remote program, it enters the send state and the remote program is in the receive state. 


The arg parameter for this request specifies the resource ID for the conversation that was 
returned by the ALLOCATE request for the conversation. 


SEND_ERROR 


7-12 


The SEND_ERROR request informs the remote transaction program that the local 
transaction program has detected an error in the information that it received from the remote 
program. 


The arg parameter for this request is a pointer to a structure of type erro_str which contains 
the input parameters for the request. Refer to the erro_str structure for a description of the 
fields in this structure. 


LU 6.2 

When this request is issued in send state, the LU: 
1. Flushes the local send buffer. 

2. Creates and sends an FMH7. 

When this request is issued in receive state, the LU: 
Generates a negative response. 

Purges all incoming data. 

Creates an FMH7. 


Waits for a send indication to arrive from the remote program. 


oo Oe 


Enters send state to send the error message. 
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LUs 1, 2, and 3 

When this request is issued in send state, the LU: 

1. Flushes the local send buffer. 

2. Sends a CANCEL request to the remote session. 

When this request is issued in receive state, the LU: 

1. Generates a negative response, using the sense_code specified in the subroutine. 


2. Purges all incoming data to the end of chain. 


The SEND_FMH request sends the FM header to the remote LU. Used only by LU 1 
support, this request must be used on a basic conversation. 


The arg parameter for this request is a pointer to a structure of type fmh_str which contains 
the input parameters for the request. Refer to the fmh_str structure for a description of the 
fields in this structure. 


The application program must build the complete FM header to be sent. If more than one FM 
header is to be sent, the application must build all FM headers with the concatenation bit set 
within a contiguous area. The application program must also enforce concatenation and 
chaining rules. | 


SEND_STATUS 


The SEND_STATUS request sends status information about the devices on the local 
session (LUs 1, 2 and 3, only) to the host program. This request can be used on a basic 
conversation only. When issued in send state, an LUSTAT is sent to the remote session 
using the ID to indicate which device the LUSTAT is for. When issued in receive state, the 
SNA_STATE return code is returned. This request is used for LU-LU sessions only. 


The arg parameter for this request is a pointer to a structure of type stat_str, which contains 
the input parameters for the status request. Refer to the stat_str structure for a description 
of the fields in this structure. 


Parameters 
fd Specifies the variable that contains the file descriptor returned by the open 
subroutine. 
request Specifies the function to be performed as defined in the luxsna.h include 
file. 
arg An integer that can be used to specify either the variable that contains the 


resource ID (rid) returned by the ioctl(ALLOCATE) subroutine or a pointer 
to a structure that contains additional input parameters for the requested 
function. 


Return Values 


When the subroutine completes successfully, it returns a value of 0. If an error occurs, the 
subroutine returns a value of —1 and sets the errno global variable to indicate the error. 


Error Codes 


The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive vary with the requested function. The 
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table in the Error Code Constants in Communications Programming Concepts section 
contains a brief description of the error values for AIX SNA Services/6000. 


File 
/usr/include/luxsna.h 
Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
Node Verification in Defining LU Type 6.2 Connection Characteristics in Communication 


Concepts and Procedures. 
The ioctl subroutine. 


The open subroutine for SNA Services/6000, read subroutine for SNA Services/6000, readx 
subroutine for SNA Services/6000, write subroutine for SNA Services/6000. 
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ioctl Subroutine for Generic SNA 


Controls data transfer between local and remote transaction programs. 


#include <sys/devinfo.h> 
#include <luxgsna.h> 


int ioctl (fildes, request, arg) 


struct devinfo “arg; 


This subroutine provides control functions for generic SNA applications. The specific control 
function is specified by the request parameter and must be one of the integers (defined in 
the luxgsna.h file) as explained in the following: 


HIER_RESET_RSP 


Purpose 
Syntax 
int fildes; 
int request, 
Description 
INOP_RSP 
IOCINFO 
Parameters 
fildes 
request 
arg 


Return Values 


The HIER_RESET_RSP function informs AIX SNA Services/6000 that 
cleanup has been done after receiving a hierarchical reset from the PU 
Services of AIX SNA Services/6000. This command is allowed only if the 
file descriptor was opened for an AIX SNA Services/6000 attachment. 


The INOP_RSP function is used to inform AlX SNA Services/6000 that 
cleanup has been done after receiving an INOP command from the PU 
Services of AIX SNA Services/6000. This command is allowed only if the 
file descriptor was opened for an AIX SNA Services/6000 attachment. 


The lIOCINFO function returns a devinfo structure that describes the device. 
After the IOCINFO operation is executed, the device type and flags 
associated with the file descriptor are returned in the devinfo structure 
pointed to by the arg parameter. 


Specifies the file descriptor return by the open subroutine. 
Specifies the function to be performed as defined in the luxgsna.h file. 


A pointer to a structure of type devinfo if the request is IOCINFO, 
(struct devinfo*). Otherwise the arg parameter is NULL. 


Upon successful completion, the ioctl subroutine returns a value of O. If an error occurs, it 
returns a value of —1 and sets errno to indicate the error. 


SNA 7-15 
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Error Codes 


The ioctl subroutine sets errno to a value which indicates the cause of any errors that 
occur, as shown in the following list: 


EBADF An invalid file descriptor was specified. 
EFAULT An invalid address was specified. 
EINVAL An invalid parameter was passed. 


Related Information 
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The close Subroutine for Generic SNA, open Subroutine for Generic SNA, read Subroutine 
for Generic SNA, write Subroutine for Generic SNA, select Subroutine for Generic SNA. 


Developing Special AIX SNA Services/6000 Functions in Communications Programming 
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ludapi Subroutine 


Purpose 
Creates 4680 commands for the ADCS Emulator. 
Syntax 
#include <lu0.h> 
#include <adscapi.h> 
extern int luOapi(); 
rc = ludapi (cmd, option, data, fname, parm1, parm2); 
short int cmd; 
short int option; 
char *data; 
char *fname; 
short int parm; 
short int parm2; 
int rc; 
Description 
The luOapi subroutine creates 4680 commands for the ADCS Emulator and places them in 
the /usr/Ipp/lu0/cmd4680 file, which is read by the adcs command when it starts the ADCS 
emulator. You must compile the lu0api.c module with your source code. 
Parameters 
cmd Specifies the code for the command to be created. Valid values for the cmd 
parameter are: 
add cmd = ADDK; 
add/replace option: 
add 
option = 0; 
replace 
option = 1; 
fname = (6 byte ascii string, blank padded, 
left justified) 


parm1 = (the number of records you wish to add) 
parm2 = (the maximum length of a logical record) 
rc = luQapi (cmd, option, data, fname, parm1, parm2); 


create cmd =CREATEF; 
fname = (6 byte ascii string, blank padded, 
left justified) 
parm1 = (how many 256 byte blocks in this file) 
parm2 = (maximum length of a logical record) 
rc = luOapi (cmd, option, data, fname, parm1, parm2); 
(fill in the next 3 fields for keyed files only) 
(short int) &data[102] = (key length) 
(short int) &data[104] = (key offset) 
(short int) &data[106] = (randomizing divisor) 
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delete 


dump 


load 


purge 


replace 


cmd = DELETEK; 
ignore error option: 
don’t ignore errors 


option = 0; 
ignore errors 
option = 1; 


fname = (6 byte ascii string, blank padded, 
left justified) 
parm1 = (the number of records you wish to delete); 
parm2 = (maximum length of a logical record); 
rc = luQapi (cmd, option, data, fname, parm1, parm2); 


cmd = DUMPF; 
fname = (6 byte ascii string, blank padded, 
left justified) 
parm1 = (relative starting sector or token); 
parm2 = (number of sectors to dump); 
rc = lu0api (cmd, option, data, fname, parm1, parm2); 


cmd =LOADF; 
replace option: 
don’t replace 


option = 0; 
replace 
option = 1; 


fname = (6 byte ascii string, blank padded, 
left justified) 
parm1 = (how many records to load) 
parm2 = (starting sector number) 
rc = ludapi (cmd, option, data, fname, parm1, parm2); 
(short int) &data[60] = (how many bytes in last sector); 


cmd = PURGEF; 


fname = (6 byte ascii string, blank padded, 
left justified) 
rc = luOapi (cmd, option, data, fname, parm1, parm2); 


cmd = REPLACEK; 
add/replace option: 


add 

option = 0; 
replace 
option = 1; 


fname = (6 byte ascii string, blank padded, 
left justified) 
parm1 = (the number of records you wish to add); 
parm2 = (maximum record length); 
rc = ludapi (cmd, option, data, fname, parm1, parm2); 


option Specifies an option dependent on the value of the cmd parameter. 


data Specifies the address where the command is stored. 


fname Specifies the address of the file that the command affects. 
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parm1 Specifies a value dependent on the value of the cmd parameter. 
parm2 Specifies a value dependent on the value of the cmd parameter. 


rc Specifies the return value indicating the success or failure of the luOapi 
subroutine. 


Return Values 


Files 


If the function is completed successfully a 0 will be returned. If the command code is not 
valid, then the LUO_CMD value is returned. 


/usr/lpp/lud/lu0.h : 
Specifies the LUO header file containing common definitions. 


/usr/lpp/lu0/adcsapi.h 
Specifies the LUO header file containing ADCS user application API 
definitions. 
/ust/pp/luO/luOapi-.h 
Specifies the LUO header file containing LUO API definitions. 
/usr/Ipp/luO/u0apis.h 
Specifies the LUO header file containing cmd4680 command file record 
formats. 
/usr/lppNu0/lu0conf.h 
Specifies the LUO header file containing configuration file definitions. 
/usr/Ipp/lu0/lu0api.c 
Specifies the C source file that defines the lu0api subroutine. 
/usr/Ipp/lu0/cmd4680 
Specifies the file containing 4680 commands, which the ADCS emulator 
program processes. 


Related Information 


The adcs command. 


Applications in Communications Programming Concepts. 
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luOclosep Subroutine 


Purpose 
Allows the application to end a session with a secondary LU. 


Syntax 
#include <lu0.h> 
extern int lu0closep(); 


rc = luOclosep (/u/ia); 


int /uid; 
int rec; 


Description 
The luOclosep subroutine closes a SNA Primary LUO session. The luOclosep subroutine 
ends a session with the secondary LU. 


Parameters 


luid Specifies the LU identifier which was returned by a previous lu0openp 
subroutine. 


rc Specifies the return value indicating the success or failure of the lu0closep 
subroutine. 


Return Values 
If the close is successful, a 0 is returned. If there are close errors, —1 is returned and the 
errno global variable is set to one of the error codes specified in the lu0.h file. 


File 


/usr/Ipp/lu0/lu0.h Specifies the LUO header file containing common definitions. 


Related Information 
The lu0ctip subroutine, lu0openp subroutine, lu0readp subroutine, luOwritep subroutine. 


Application Program Interface in Communications Programming Concepts. 
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luOcloses Subroutine 


Purpose 
Allows the application to end a session with a host application. 


Syntax 
#include <lu0.h> 
extern int ludcloses(); 


rc = luOcloses (/uid); 


int /uid; 
int rc; 


Description 
The luOcloses subroutine closes the SNA Secondary LUO session. The lu0closes 
subroutine ends a session with the host application. 


Parameters 
luid Specifies the LU identifier that was returned by the luOopens subroutine. 


rc Specifies the return value indicating the success or failure of the lu0closes 
subroutine. 


Return Values 
If the close is successful, a 0 is returned. If there are close errors, —1 is returned and the 
errno global variable is to one of the error codes specified in the lu0.h file. 


File 


/usr/ipp/lu0/lu0.h Specifies the LUO header file containing common definitions. 


Related Information 
The luOctls subroutine, luOopens subroutine, luOreads subroutine, luOwrites subroutine. 


Application Program Interface in Communications Programming Concepts. 
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luOctlp Subroutine 


Purpose 
Allows the application to send SNA commands to the secondary LU. 
Syntax 
— #include <iu0.h> 
extern int luOctlp(); 
re = lu0ctip(/uid, senseptr, optcode) 
int /uid; 
char *senseptr, 
int optcode; 
int re; 
Description 
The luOctip subroutine sends SNA commands or responses to the secondary LU. 
Parameters 
luid Specifies the LU identifier which was returned by the luQopenp subroutine. 
senseptr Points to the address of the sense data buffer (6 bytes). 
optcode Specifies the option code. The following are valid values for the optcode 
parameter: 
LUOACPT Sends accept to previous request. 
LUOREJ Sends reject to previous request, parm2 has 4 bytes of 
sense data. 
LUORSTAT Receives sense bytes(6) from LUSTAT or response 
information into parm2 buffer. 
LUOFSM Returns 4 FSM bytes into parm2 buffer. 
LUOSDT Sends sdt. 
LUOCLEAR Sends clear. 
LUOSTSN Sends stsn, parm2 has ru data, 5 bytes. 
LUOSTAT Sends lustat, parm2 has 4 sense bytes. 
LUOQEC Sends quiesce at end of chain. 
LUOQC Sends quiesce complete. 
LUORELQ Sends release quiesce. 
LUOCAN Sends cancel partially sent chain. 
LUOCHASE Sends chase. 
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LUOSHUTD Sends shutdown. 


LUOBID Sends bid. 
LUOSIG Sends signal, parm2 has 4 sense bytes. 

rc Specifies the return value indicating the success or failure of the lu0ctip 
subroutine. 


Return Values 
If the function completes successfully, a 0 will be returned. If errors are encountered, —1 is 


returned and the errno global variable is set to one of the error codes specified in the lu0.h 
file. 


File 
/usr/lpp/lu0/lu0.h Specifies the LUO header file containing common definitions. 
Related Information 


The lu0closep subroutine, lu0openp subroutine, lu0readp subroutine, luOwritep 
subroutine. 


Application Program Interface in Communications Programming Concepts. 
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luOctis Subroutine 


Allow the application to send SNA commands to the host. 


re = lu0ctls(/uid, senseptr, optcode); 


The lu0ctls subroutine controls function for SNA Secondary LUO sessions. The IuOctis 
subroutine sends SNA commands or responses to the host system. The /uid parameter is 
the LU identifier returned on a previous luQopens subroutine. 


Specifies the LU identifier that was returned by the lu0opens subroutine. 


Points to the address of the sense data buffer (6 bytes). 


Specifies the option code. The following are valid values for the optcode 


parameter: 
LUOACPT 
LUOREJ 


LUORSTAT 


LUOFSM 
LUORQR 
LUOSTAT 
LUORTR 
LUOQEC 
LUOQC 
LUORELQ 
LUOCAN 
LUOCHASE 


Purpose 
Syntax 
#include <lu0.h> 
extern int lu0ctls(); 
int /uid; 
char *senseptr, 
int optcode; 
int rc; 
Description 
Parameters 
luid 
senseptr 
optcode 
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Sends accept to previous request. 


Sends reject to previous request, parm2 has 4 bytes of 
sense data. 


Receives sense bytes (6) from LUSTAT or response 
information into parm2 buffer. 


Returns 4 FSM bytes into parm buffer. 
Sends request recovery. 

Sends lustat, parm2 has 4 sense bytes. 
Sends ready to receive. 

Sends quiesce at end of chain. 
Sends quiesce complete. 

Sends release quiesce. 

Sends cancel partially sent chain. 


Sends chase. 


luOctis 


LUOSHUTC Sends shutdown complete. 


LUOSIG Sends signal, parm2 has 4 sense bytes. 
rc Specifies the return value indicating the success or failure of the luOctls 
subroutine. 


Return Values 
If the function completes successfully a 0 is returned. If errors are encountered, —1 is 


returned and the errno global variable is set to one of the error codes specified in the lu0.h 
file. 


File 
/usr/Ipp/lu0/lu0.h Specifies the LUO header file containing common definitions. 
Related Information 


The luOcloses subroutine, luOopens subroutine, luOreads subroutine, luOwrites 
subroutine. 


Application Program Interface in Communications Programming Concepts. 
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lu0openp Subroutine 


Purpose 
Allows the application to begin a session with a secondary application. 


Syntax 
#include <lu0.h> 
extern int lu0openp(); 


= luQopenp (/uname, bindptr, bindlenp); 
char */uname; 
char *bindptr, 
int *bindlenp; 
int rc; 


Description 
The luQopenp subroutine opens a SNA Primary LUO session. The luQopenp subroutine 


opens a session with the secondary application. The value returned for me luid parameter is 
used on subsequent operations to define the LU identifier. 


Parameters 


luname Specifies the address of an 8 byte name in the configuration file. The name 
should be left justified and padded with spaces. 


bindptr Points to the address of a 256 byte bind record buffer. On input to this 
routine, if the buffer contains a bind record (first byte = 0x31), then it will be 
the bind record sent to the secondary LU. Otherwise, the bind record is 
formatted from the information in the configuration file LU record and will be 
copied into this buffer. 


bindlenp Specifies the address of the integer that contains the length of the bind 
record. If the bind record is formatted by the caller in parm 2, then parm 3 
should point to an integer that contains the length of the bind record. 
Otherwise parm 3 should point to an integer into which the length of the bind 
record is returned. 


re Specifies the return value indicating the success or failure of the luQopenp 
subroutine. 


Return Value 
If the open is successful, the LU identifier is returned. The LU identifier is actually the 
address of the LUO table entry in shared memory. If there are open errors, —1 is returned 
and the errno global variable is set to one of the error codes specified in the Iu0.h file. 


File 


/ust/Ipp/lu0/lu0.h Specifies the LUO header file containing common definitions. 


Related Information 
The luOclosep subroutine, !uOctip subroutine, luOreadp subroutine, luOwritep subroutine. 


Application Program Interface in Communications Programming Concepts. 
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ludopens Subroutine 


Purpose 
Allows the application to begin a session with a host application. 
Syntax 
#include <lu0.h> 
extern int lu0opens(); 
luid = lu0opens (/uname, bindptr, bindlenp); 
int /uid; 
char */uname; 
char *bindptr, 
int *bindlenp; 
Description 
The lu0opens subroutine opens a SNA Secondary LUO session. The luQopens subroutine 
opens a session with the host application. The value returned for the /uid parameter is used 
on subsequent operations to define the LU identifier. 
Parameters 
luname Specifies the address of an 8-byte name in the configuration file. The name 
should be left-justified and padded with spaces. 
bindptr Points to the address of a 256 byte buffer into which the bind record is 
placed. 
bindlenp Specifies the address of the integer into which the length of the bind record 
is placed. 
luid Specifies the return value indicating the success or failure of the ludopens 
subroutine. 


Return Values 
If the open is successful, the LU identifier is returned. The LU identifier is actually the 
address of the LUO table entry in shared memory. After a successful open, the application 
should check the bind record that was returned. It should then call the luOctls subroutine 
with the LUOACPT function code to accept the BIND request or the LUOREJ function code to 
reject the BIND request. No other processing can be done until the bind has been responded 
to. If there are open errors, —1 is returned and the errno global variable is set to one of the 
error codes specified in the !u0.h file. 


File 


/ustippAud/lu0.h Specifies the LUO header file containing common definitions. 


Related Information 
The luOcloses subroutine, luOctis subroutine, luOreads subroutine, luOwrites subroutine. 


Application Program Interface in Communications Programming Concepts. 
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luOreadp Subroutine 


Purpose 
Allows the application to receive data from the secondary LU. 
Syntax 
#include <lu0.h> 
extern int ludreadp 0; 
rc = luOreadp(/uid, buffptr, bufflen) 
int /uid; 
char *buffptr, 
int bufflen; 
int rc; 
Description | 
The luOreadp subroutine reads a request from a SNA Primary LUO session. The luOreadp 
subroutine receives data from the secondary LU. , 
Parameters 
luid Specifies the LU identifier returned by the luQopenp subroutine. 
buffptr Points to the address of the PIU buffer. 
bufflen Specifies the length of the PIU buffer. The buffer length should be long 
enough to hold the largest request plus the SNA TH and RH. 
rc Specifies the return value indicating the success or failure of the luOreadp 
subroutine. 


Return Value 
If the read is successful, the length of the PIU is returned If there are read errors, —1 is 


returned and the errno global variable is set to one of the error codes specified in the lu0.h 
file. 


File 


/usr/lpp/lu0/lu0.h = Specifies the LUO header file containing common definitions. 


Related Information | 
The luOclosep subroutine, luOctlp subroutine, luOopenp subroutine, luOwritep subroutine. 


Application Program Interface in Communications Programming Concepts. 
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luOreads Subroutine 


Purpose 
Allows the application to receive data from the host application. 
Syntax 
#include <lu0.h> 
extern int luOreads(); 
re = luQreads(/uid, buffotr, bufflen); 
int /uid; 
char *buffptr; 
int bufflen; 
int rc; 
Description 
The luOreads subroutine reads a request from a SNA Secondary LUO session. The 
luOreads subroutine receives data from the host application. 
Parameters 
luid Specifies the LU identifier returned by the luOopens subroutine. 
buffptr Points to the address of the PIU buffer. 
bufflen Specifies the length of the PIU buffer. The buffer length should be long 
enough to hold the largest request plus the SNA TH and RH. 
rc Specifies the return value indicating the success or failure of the luOreads 
subroutine. 


Return Value 
If the read is successful, the length of the PIU is returned. If there are read errors, —1 is 
returned, and the errno global variable is set to one of the error codes specified in the lu0.h 
file. 


File 


/usr/lpp/lu0/lu0.h Specifies the LUO header file containing common definitions. . 


Related Information 
The luOcloses subroutine, luOctls subroutine, luOopens subroutine, luOwrites subroutine. 


Application Program Interface in Communications Programming Concepts. 
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luOwritep Subroutine 


Purpose 


Allows the application to send data to the secondary LU. 


Syntax 


#include <lu0.h> 
extern int lu0writep(); 


rc = luOwritep(/uid, buffptr, bufflen); 


int /uid; 
char *buffotr, 
int bufflen; 


int re; 


Parameters 
luid 
buffptr 
bufflen 


rc 


Description 


Specifies the LU identifier returned by a previous luQopenp subroutine. 
Points to the address of the PIU. 
Specifies the length of the PIU. 


Specifies the return value indicating the success or failure of the luOwritep 
subroutine. 


The luOwritep subroutine writes a request ina SNA Primary LUO session. The luOwritep 
subroutine sends data to the secondary LU. The following fields will be set in the TH and 


RH: 
TH 


RH 


Return Value 


FID type = 2 


Destination address field 
Origination address field 
Sequence number field 


Type = request 


RU category = FMD 

No sense data 

No enciphered data 

No padded data 

No conditional end bracket 


If the write is successful, the length of the PIU is returned If there are write errors, —1 is 
returned and the errno global variable is set to one of the error codes specified in the lu0.h 


file. 
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File 
/usr/Ipp/lu0/lu0.h 
Specifies the LUO header file containing common definitions. 


Related Information 
The luOclosep subroutine, luOctlp subroutine, luOopenp subroutine, luOreadp subroutine. 


Application Program Interface in Communications Programming Concepts. 
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luQwrites Subroutine. 


Purpose 
Allows the application to send data to the host application. 
Syntax 
#include <lu0.h> 
extern int luOwrites(); 
rc = luOwrites (/uid, buffptr, bufflen); 
int /uid; 
char *buffptr, 
int bufflen; 
int rc; 
Description 
The luOwrites subroutine writes a request in a SNA Secondary LUO session. The luOwrites 
subroutine sends data to the host application. The following fields are set in the TH and RH: 
TH FID type = 2 
Destination address field 
Origination address field 
Sequence number field 
RH Type = request 
RU category = FMD 
No sense data 
No enciphered data 
No padded data 
No conditional end bracket 
Parameters 
luid Specifies the LU identifier returned by the lu0opens subroutine. 
buffptr Points to the address of the PIU. 
bufflen Specifies the length of the PIU. 
re Specifies the return value indicating the success or failure of the luOwrites 
subroutine. 


Return Value | 
If the write is successful, the length of the PIU is returned If there are write errors, —1 is 


returned and the errno global variable is set to one of the error codes specified in the lu0.h 
file. 
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File 
/usr/lpp/lu0/lu0.h 
Specifies the LUO header file containing common definitions. 


Related Information 
The luOcloses subroutine, luOctls subroutine, lu0opens subroutine, lu0Oreads subroutine. 


Application Program Interface in Communications Programming Concepts. 
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nm_close Subroutine 


Purpose 
Releases the SSCP_PU session. 
Syntax 
int nm_close (sscp_ia) 
char *sscp_id; 
Description 
An application uses the nm_close subroutine to release the specified session so another 
application can use it. 
Parameter 


sscp_id An ID predefined by the host for a specific SSCP—PU session. 


Return Values 
When the subroutine completes successfully, it returns a 0 (zero) to indicate that the 


specified session is closed. Otherwise, the subroutine returns a value of —1 and sets the 
errno global variable to indicate the error. 


Error Code 
The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown below. Error Code Constants 


in Communications Programming Concepts contains a brief description of the error values 
for AIX SNA Services/6000. 


SNA_INVALID 
File 


/usr/include/luxsna.h 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The nmopen subroutine, nmsend subroutine, nmrecv subroutine, nmstat subroutine. 
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nm_open Subroutine 


Purpose 
Establishes the SSCP_PU session. 


Syntax 
int nm_open (sscp_id, application_server_name, sna_server_name) 
char *sscp_id; 
char *application_server_name; 
char *sna_server_name; 


Description 
An application uses the nm_open subroutine to associate itself with the specified session. 
The nm_open subroutine should be the first network management API subroutine called. 


Parameters 
sscp_id An ID predefined by the host for a specific SSCP-—PU session. 


application_server_name 


A pointer to the application server name. The argv{0] parameter contains 
the server name. 


sna_server_name 


A pointer to the sna server name. If the name pointer is NULL, the default 
SNA server name is sna. 


Return Values 
When the subroutine completes successfully, it returns a zero to indicate that the specified 
session is active and not being used by another application. Otherwise, the subroutine 
returns a value of —1 and sets the errno global variable to indicate the error. 


Error Codes 
The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 
Code Constants in Communications Programming Conceptscontains a brief description of 
the error values for AIX SNA Services/6000. 


SNA_ERP SNA_INACT 
SNA_INUSE SNA_NOTAVAIL 
SNA_UNDEF_SVR 

File 
/usr/include/luxsna.h 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The nm_send subroutine, nm_recv subroutine, nm_close subroutine, nm_stat subroutine. 
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nm_receive Subroutine 


Purpose 
Receives NMVT data from the specified SSCP_PU session. 
Syntax 
int nm_receive (sscp_id, buffer, length, type) 
char *sscp_id; 
char *buffer, 
int /Jength 
int *type 
Description 
An application uses the nm_receive subroutine to receive NMVT data for the specified 
session. lf no data is available for that session, the subroutine waits until data is available or 
until the application ends the subroutine. 
Parameters 
sscp_id An ID predefined by the host for a specific SSCP-—PU session. 
buffer A pointer to the buffer area where the data is received. 
length The number of bytes of data. If this value is less that the actual number of 
bytes received, the message is truncated and the remainder is discarded. 
type The type of data. The following types are returned: 
0 Request 
1 Positive response 
2 Negative response. 


Return Values 
When the subroutine completes successfully, it returns a positive integer that indicates the 


number of bytes received and placed in the user buffer. Otherwise, the subroutine returns a 
value of —1 and sets the errno global variable to indicate the error. 


Error Codes 
The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 


Code Constants in Communications Programming Concepts contains a brief description of 
the error values for AIX SNA Services/6000. 


SNA_ERP 
SNA_INVALID 
SNA_INACT 

SNA_LENGTH 
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File 
/usr/include/luxsna.h 
Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The nm_open subroutine, nm_send subroutine, nm_close subroutine, nm_stat 
subroutine. 
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nm_send Subroutine 


Purpose 
Sends NMVT data to the specified SSCP_PU session. 
Syntax 
int nm_send (sscp_id, data, length, type) 
char *sscp_id; 
char *data; 
int /ength 
int type 
Description 
An application uses the nm_send subroutine to send NMVT data, including the NMVT 
header, to the specified session. The application must specify the data, the data length and 
the data type. SNA sets RH according to the data type: 
request 0x0B8000 
positive response 0x838000 
negative response 0x879000 
Parameters 
sscp_id An ID predefined by the host for a specific SSCP-—PU session. 
data A pointer to the buffer area from which the data is sent. The data should 
contain a sense code if the type parameter is negative response. 
length The number of bytes of data sent 
type The type of data. The following types are allowed: 
0 Request 
1 Positive response 
2 Negative response. 


Return Values 
When the subroutine completes successfully, it returns a positive integer that indicates the 


number of bytes sent. Otherwise, the subroutine returns a value of —1 and sets the errno 
global variable to indicate the error. 
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Error Codes 
The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 
Code Constants in Communications Programming Concepts contains a brief description of 
the error values for AIX SNA Services/6000. 


SNA_ERPSNA_INACT 
SNA_NMVT_HDR 
SNA_INVALID 
SNA_LENGTH 
SNA_STATE 

File 
/usr/include/luxsna.h 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The nm_open subroutine, nm_recv subroutine, nm_close subroutine, nm_stat subroutine. 
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nm_status Subroutine 


Purpose 
Provides the status of the specified SSCP_PU session. 
Syntax 
int nm_status (sscp_id) 
char *sscp_id; 
Description 
An application uses the nm_status subroutine to obtain the status of a session. There are 
three types of status: active, inactive, and reset. 
Parameter 


sscp_/D An ID predefined by the host for a specific SSCP—PU session. 


Return Values 
When the subroutine completes successfully, it returns a 0 (zero) to indicate that the 


specified session is active. Otherwise, the subroutine returns a value of —1 and sets the 
errno global variable to indicate the error. 


Error Codes 
The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 


Code Constants in Communications Programming Concepts contains a brief description of 
the error values for AIX SNA Services/6000. 


SNA_ERP (reset) 

SNA_INVALID 

SNA_INACT (inactive) 
File 


/usr/include/luxsna.h 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The nm_open subroutine, nm_send subroutine, nm_recv subroutine, nm_stat subroutine. 
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open Subroutine for SNA Services/6000 


Purpose 
Opens a resource. 
Syntax 
#include <luxsna.h> 
int open(path, oflag) 
char *path; 
int oflag; 
Description 


The open subroutine for AIX SNA Services/6000 initializes a connection to a resource 
described in a specified connection profile. You must use the open subroutine before using 
any other SNA subroutine for a particular connection. Each open subroutine ties a local LU 
to a remote LU. 


Note: Opening a connection causes the associated attachment to be started if the 
attachment is not already active. 


Limited Interface 


When the connection profile defines the connection to be Limited, the open subroutine 
also allocates the conversation between the local LU and the remote LU using the 
connection created by the open subroutine. The allocation uses the default allocation 
parameters as defined in the connection profile. Only one conversation can be allocated to 
this connection. 


Extended Interface 


The calling program must also allocate conversations to the connection after it is opened. 
Use the ioctl subroutine to perform the allocation. 


For LUs 1, 2 and 3, only two sessions (SSCP—LU, LU-LU) can be allocated to a particular 
open file descriptor (connection). However, for LU 6.2 several conversations can be 
allocated to an open file descriptor. 


Parameters 


path Specifies the resource to be opened. It must be in the form: 
ddn/cpn[/tpn] 


The parameters in this string have the following meanings: 


ddn Specifies the SNA device driver name to be used to open the 
resource. This will always be in the /dev/sna directory. 

cpn Specifies the connection profile name of the resource to be 
opened. 
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tpn Specifies the remote transaction profile name to be used in place 
of the transaction profile name found in the connection profile. _ 
This parameter is optional. If you do not specify this parameter, 
the open subroutine uses the remote transaction profile name 
found in the connection profile. If you specify this parameter, 
separate it from the connection profile name with a / (slash). 


oflag Specifies a value to set the file status flag. The offag parameter values for 


the SNA device driver are constructed by logically ORing flags from the 
following list: 


O_RDWR Open for reading and writing 


O_NDELAY = Subsequent reads will return immediately if no data is 
present. 


Return Values 
When the routine completes successfully, it returns a non—negative integer that specifies the 
file descriptor (fildes) or connection ID (cid) for the connection. If an error occurs, the 
routine returns a value of —1 and sets the errno global variable to indicate the error. 


Error Codes 
The routine sets the errno global variable to a value to indicate the cause of any errors that 
occur. The values that this variable can receive are shown in following list. Error Code 
Constants in Communications Programming Concepts contains a brief description of the 
following error values for AIX SNA Services/6000: 


ENOENT ENOMEM 
EMFILE ENXIO 
ENOTDIR ETXTBSY 
EACCES EROFS 
EFAULT EISDIR 


File 
/usr/include/luxsna.h 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The open subroutine, close subroutine. 


The close subroutine for SNA Services/6000, ioctl subroutine for SNA Services/6000, 
snaopen subroutine for SNA Services/6000. 
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open Subroutine for Generic SNA 


Purpose 
Opens a file descriptor. 


Syntax 


#include <luxgsna.h> 


int openx(path, oflag, mode, ext) 
char *path; 

int oflag; 

int mode; 

int ext, 


Description 
The open subroutine initializes resources to tie an AIX SNA Services/6000 attachment to a 
tile descriptor such that each file descriptor corresponds to an AIX SNA Services/6000 
attachment. This command must be issued before using any other generic SNA device 
driver subroutine. 


Parameters | 
path Specifies the resource to be opened. It must be in the following form: 


/dev/gsna/attachment_profile_name 


The attachment_profile_name in the path is required. It is used to 
start an AIX SNA Services/6000 attachment only if AIX SNA Services/6000 
is running and an appropriate AIX SNA Services/6000 attachment profile is 
defined. AIX SNA Services/6000 supports only PU type 2.1 nodes. 


oflag Specifies the value of the file status flag. The generic SNA device driver 
uses only the following values of this flag (all other values are ignored): 


O_RDWR Open for reading and writing 
O_NDELAY Subsequent reads will return immediately if no data 
is present. 
mode Ignored by generic SNA. 
ext Ignored by generic SNA. 


Return Values 
Upon successful completion, the open subroutine returns a 0 (zero). If an error occurs, it 
returns a value of —1 and sets errno to indicate the error. 
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Error Codes 
The open subroutine sets errno to a value which indicates the cause of any errors that 
occur. The values that errno can receive are shown in the following list: 


ENXIO 
ENOENT 
EACCES 


ENOMEM 


EISDIR 


ENOTDIR 
ETXTBSY 


EROFS 


EMFILE 
EFAULT 


SNA_NO_LU 
SNA_FAIL 


Related Information 
The close Subroutine for Generic SNA, read Subroutine for Generic SNA, write Subroutine 
for Generic SNA, ioctl Subroutine for Generic SNA, select Subroutine for Generic SNA. 
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No such device or address exists. 
The named file does not exist. 


A component of the path prefix denies search permission, or 
permission is denied for the named file. 


Either this node or the server does not have enough memory 
available to service the request. 


The named file is a directory, and the oflag parameter is write or 
read/write. 


A component of the path prefix is not a directory. 


The file is a pure procedure (shared text) file that is being executed 
and the oflag parameter is write or read/write. 


The named file resides on a read-only file system, and the oflag 
parameter is write or read/write. 


The maximum number of file descriptors are currently open. 


The path parameter points to a location outside the process’s 
allocated address space. 


No LUs are registered for the Generic SNA device driver. 


SNA system failure. SNA is not currently running. 


Developing Special AIX SNA Services/6000 Functions in Communications Programming 


Concepts. 
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read Subroutine for SNA Services/6000 


Purpose 
Receives data from the remote transaction program. 


Syntax 


#include <luxsna.h> 


int read(fildes, data, length) 
int fildes; 


char *data; 
int length; 


Description | 
Note: Use this subroutine for LU 6.2 limited connections only. Applications using LU 6.2 
extended connections or LU 1, LU 2, or LU 3 connections should use the readx 
subroutine. 


The read subroutine waits for information to arrive on the specified conversation and then 
receives the information. If the information is already available, it receives the information 
without waiting. 


When trying to read froma conversation that has no data available, the state of the 
O_NDELAY flag (see the open or fentl subroutines) determines what happens to the read 


operation: 
set The read returns a value of 0 to indicate that no data has been received. 
clear The read is blocked until data becomes available. 


An application program should not use the read subroutine unless the program is performing 
a very simple function. Use the readx subroutine instead. The readx subroutine returns 
additional information to inform the application program what state it is in. The read 
subroutine does not provide that information. 


If the application program uses this command when the conversation is in send state, the 
following actions occur: 


1. The LU flushes its send buffer, sending all buffered information and the send indication to 
the remote program, 


2. The local program enters the receive state and waits for data from the remote program. 
Extended Interface 


When using the extended interface for LU 6.2 connections with multiple conversations, only 
the first conversation is accessible with this command. 


Parameters 
fildes Specifies the variable that contains the file descriptor returned by the open 
subroutine. 
data Specifies a pointer to the buffer area into which the data will be read. 
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length Specifies the variable that contains a value indicating the maximum number 
of bytes of data to be received. This value cannot be larger than 32,764 


(32K — 4) bytes. 


Return Values 
When the subroutine completes successfully, it returns a positive integer that indicates the 
number of bytes received. If an error occurs, the routine returns a value of —1 and sets the 
errno global variable to indicate the error. 


If an interrupt occurs while the subroutine is processing, it returns the number of bytes that 
have already been transferred to the user buffer. If no data has been moved when the 
interrupt occurs, it returns a value of —1 and sets the errno global variable to EINTR. 


Error Codes 
The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 

Code Constants in Communications Programming Concepts contains a brief description of 


File 


the following error values for AIX SNA Services/6000: 


EBADF 

EINTR 
EINVAL 
ENOMEM 
SNA_ALFN 
SNA_ALFR 
SNA_BOUNDARY 
SNA_CTYPE 
SNA_INVACC 
SNA_NOCONN 
SNA_NOTPN 


/usr/include/uxsna.h 


SNA_NPIP 
SNA_NREC 
SNA_NRMDEAL 
SNA_NRREC 
SNA_NSES 
SNA_NSYC 
SNA_PGMDEAL 
SNA_PNREC 
SNA_PNSYC 
SNA_PNTR 
SNA_PPURG 


SNA_PROTOCOL 
SNA_PTR 
SNA_RFN 
SNA_RFR 
SNA_RREC 
SNA_SNTR 
SNA_SPURG 
SNA_STATE 
SNA_SVCDEAL 
SNA_TIMDEAL 
SNA_WRGPIP 


Defines constants and structures used by AIX SNA Services/6000 


subroutines. 


Related Information 
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The read subroutine. 


The write subroutine for SNA Services/6000, ioctl subroutine for SNA Services/6000, open 
subroutine for SNA Services/6000. 
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read Subroutine for Generic SNA 


Purpose 
Receives data from a file descriptor. 
Syntax 
#include <luxgsna.h> 
int read (fildes, data, length) 
int readx (fildes, data, length, ext) 
int fildes; 
char “data; 
int length; 
int ext; 
Description 
The read subroutine receives normal sequenced data, exchange ID (XID) data, network 
data, or datagram data. 
A read subroutine can be issued for normal data when the open subroutine has completed 
successfully. 
The read subroutine waits for information to arrive on the specified AIX SNA Services/6000 
attachment, then receives the information. If information is already available, it receives the 
information without waiting. 
Parameters 
fildes Specifies the file descriptor returned by the open subroutine. 
data Specifies a pointer to the buffer area into which the data will be read. 
length Specifies the maximum number of bytes of data to be received. This value 


cannot be larger than 32,764 (32K — 4) bytes. 
ext Ignored by generic SNA. 


Return Values 
Upon successful completion, this subroutine returns a non-negative integer that indicates 


the number of bytes received. If an error occurs, it returns a value of —1 and sets errno to 
indicate the error. 


Error Codes 


The call sets errno to a value that indicates the cause of any errors that occur, as shown in 
the following list: 


EBADF An invalid file descriptor was specified. 
EFAULT An invalid address was specified. 
EINTR The read subroutine was interrupted. 
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EINVAL An invalid parameter was passed. 

SNA_HIER_RESET Hierarchical Reset was received from AIX SNA 
Services/6000. 

SNA_INOP INOP was received from AIX SNA Services/6000. 

SNA_FAIL SNA system failure. 


Related Information 


The close Subroutine for Generic SNA, open Subroutine for Generic SNA, write Subroutine 
for Generic SNA, ioctl Subroutine for Generic SNA, select Subroutine for Generic SNA. 


Developing Special AIX SNA Services/6000 Functions in Communications Programming 
Concepts. 
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readx Subroutine for SNA Services/6000 


Purpose 

Receives data from the remote transaction program. 
Syntax 

#include <luxsna.h> 

int readx (fildes, data, length, ext) 

int fildes; 

char *data; 

int /ength; 

struct ext_io_str *ext; 
Description 


Note: Do not use this subroutine for LU 6.2 programs that use the limited interface. 


The readx subroutine waits for information to arrive on the specified conversation and then 
receives the information. If the information is already available, it receives the information 
without waiting. The information can be data, conversation status, or a request for 
confirmation. The connection profile for this connection must designate the use of the 
extended interface as described in Defining AIX SNA Services/6000 Characteristics in 
Communication Concepts and Procedures. 


Note: SNA Services defines all LU 1, LU 2, and LU 3 connections as extended interface 
connections. 


If the application program uses this command when the conversation is in send state, the 
following actions occur: 


1. The LU flushes its send buffer, sending all buffered information and the send indication to 
the remote program, 


2. The local program enters the receive state and waits for information from the remote 
program. 


If you specify the rid parameter in the ext_io_str structure to be 0 (zero) or NULL, the 
subroutine performs a read any operation. The data that the routine returns is from the first 
resource allocated to the connection that has data available. The subroutine then sets the 
rid parameter to indicate the resource ID of the resource that supplied the data. 


When trying to read from a conversation that has no data available, the state of the 
O_NDELAY flag (see the open or fentl subroutine) determines what happens to the read 
operation: 


set The read returns a value of 0 to indicate that no data has been received. 
clear The read is blocked until data becomes available. 


When header information is received, it is moved into the usrhdr field of the extended I/O 
structure, ext_io_str. If the header information is longer than the space allowed (specified in 
the usrhdr_len parameter), the usr_trunc field is set to indicate the error. No 
information, data or header is returned when the header is truncated. 
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The ext parameter points to a structure that contains additional input and output parameters 
for the readx subroutine. This same structure is used for the writex subroutine. Refer to the 
ext_io_str structure for a description of the fields. The readx subroutine uses only the 
following fields in that structure: 


e deallocate 

e deallo_type (type=B’010’ only - deallocate with abnormal end of conversation) 
e deallo_ flag 

e allocate 

e fill 

e sess_type 

e rq_to_snd_revd 

e what_data_rcvd 

e what_control_rcvd 
e sense_code 

e rid 

e usrhdr_len 

e usr_trunc 


e usrhdr 


User Header Field 


In addition to the data provided in the extended I/O structure, the sending program can 
supply header information about the data being sent. The receiving program must allow for 
receiving this information by doing the following: 


1. Define the length of the header information in the usrhdr_len field. 


2. Reserve consecutive space following the extended I/O structure (ext_io_str) for the 
header information. 


3. Pass the extended I/O structure pointer (the ext parameter) in a readx subroutine. 


LUs 1, 2 and 3 
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The amount of data returned depends upon the type of information read (FM header or 
data), the length specified in the read, and the size of the data. For FM headers data, the 
amount of data depends upon the size of the FM header. For a chain element, the amount of 
data depends upon the size of the chain element request unit. 


Use only the buffer value for the £i11 option. Use confirm_deallocate and 


normal_deallocate parameters only on an LU-LU session to indicate the end of a 
bracket. 


Do not use the following: 

e confirm _deallocate_retain 

¢ normal_deallocate_retain 

e confirm_deallocate on an SSCP-LU session 


e normal_deallocate on an SSCP-LU session. 
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When FM header data is received, the FM header data is moved to the user buffer. The 
what_data_rcvd field is set to indicate the receipt of FM header data. If data was received 
in addition to the FM header data, a separate readx subroutine must be issued to obtain the 
data. 


lf the host bids for the session, a readx subroutine with the allocate bit on accepts the bid. 
For additional information, refer to the ALLOCATE section of the ioctl subroutine and to the 
writex subroutine. 


Parameters 

fildes Specifies the variable that contains the file descriptor returned by the open 
subroutine. 

data Specifies a pointer to the buffer area into which the data will be read. 

length Specifies the variable that contains a value indicating the maximum number 
of bytes of data to be received. This value cannot be larger than 32,764 
(32K — 4) bytes. 

ext Specifies a pointer to an extended |/O structure of type ext_io_str. The 


ext_io_str structure allows the user to combine functions into one routine. 
You can use readx(ALLOCATE and DEALLOCATE) on one routine. This 
structure type is defined in the luxsna.h include file. See the ext_io—str 
structure. 


Return Values 
When the subroutine completes successfully, it returns a positive integer that indicates the 
number of bytes received. If an error occurs, the routine returns a value of —1 and sets the 
errno global variable to indicate the error. 


if an interrupt occurs while the subroutine is processing, it returns the number of bytes that 
have already been transferred to the user buffer. If no data has been moved when the 
interrupt occurs, it returns a value of —1 and sets the errno global variable to EINTR. 


Error Codes 
_ The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 
Code Constants in Communications Programming Concepts contains a brief description of 
the following error values for AIX SNA Services/6000: | 


EBADF SNA_NPIP SNA_PROTOCOL 
EINTR  SNA_NREC SNA PTR 
EINVAL SNA_NRMDEAL SNA_RFN 
ENOMEM SNA_NRREC SNA_RFR 
SNA_ALFN SNA_NSES SNA_RREC 
SNA_ALFR SNA_NSYC SNA_SNTR 
SNA_BOUNDARY SNA_PGMDEAL SNA_SPURG 
SNA_CTYPE - SNA_PNREC SNA_STATE 
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SNA_INVACC SNA_PNSYC SNA_SVCDEAL 
SNA_NOCONN SNA_PNTR SNA_TIMDEAL 
SNA_NOTPN SNA_PPURG SNA_WRGPIP 


File 
/usr/include/luxsna.h 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The readx subroutine. 


The writex subroutine for SNA Services/6000, ioctl subroutine for SNA Services/6000, 
open subroutine for SNA Services/6000, snaread subroutine for SNA Services/6000. 
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select Subroutine for SNA Services/6000 


Purpose 


Syntax 


Examines a file descriptor or message queue. 


#include <sys/time.h> 
#include <sys/select.h> 


int select(nfdsmsgs, readlist, writelist, exceptlist, timeout) 
ulong nfdsmsgs; 

void *readiist; 

void *writelist; 

void *excepllist; 

struct timeval * timeout; 


Description 


The select subroutine examines a set of resource IDs (file descriptors) to determine how 
many of the indicated resources: 


e Are available for reading or receiving data 

e Are available for writing or sending data (not supported by AIX SNA Services/6000) 
e Have an outstanding exceptional condition. 

Exceptional conditions include the status conditions listed in the gstat_str structure. 


AIX SNA Services/6000 supports the select(data received) and select(exceptional 
conditions) subroutines. 


A time-out value is also provided to prevent the subroutine from waiting for a response for 
too long a period of time. 


Each of the operations (read, write or exception) is described with a structure of type 
sellist that is defined in the /usr/include/sys/select.h file. This structure is defined as 
follows: 


struct sellist 


{ 
long fdsmask[ ]; 
long msgids[ ]; 
. 


The additional parameters have the following meanings: 


fdsmask{ ] Specifies an array of int values that are used as a continuous stream of 
bits. Each long value contains 32 bits, so that the first array member 
contains bits 0 through 31, the second array member contains bits 32 
through 63, and so forth. The bit number plus one corresponds to the file 
descriptor that the number represents (that is, bit 35 represents file 
descriptor 36). The SELECT operation examines all file descriptors up to 
the limit specified in the nfdsmsgs parameter for the condition 
corresponding to this structure (read, write, or exception). When the 
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msgids{ ] 


subroutine returns, it sets the bits in this structure that represent the file 
descriptors that satisfied the examination to a value of 1. To disable 
file-descriptor checking for an operation, set all members of this array toa 
value of 0. 


Specifies an array of int values. Each long value is a message queue 
identifier that specifies a message queue to be examined. The select 
operation examines the message queues for each ID up to the number of 
IDs indicated by the limit specified in the nfds parameter for the condition 
corresponding to this structure (read, write, or exception). When the 
subroutine returns, it sets all members of this array whose queues do not 
satisfy the examination to a value of OxFFFFFFFF. 


Message queue checking is not supported by AIX SNA Services/6000 and should be 
disabled by setting all members of this array to a value of OxFFFFFFFF. The value provided 
in the nfdsmsgs parameter determines the size that must be given to the fdsmask[ ] and 
msgids[ ] arrays. . 


The /usr/include/sys/select.h header file also defines two macros to help split the 
nfdsmsgs parameter and the return value into their component halves: 


NFDS(nfdsmsgs) Extracts the number of file descriptors. 


NMSGS(nfdsmsgs) Extracts the number of message queues. 


Parameters 
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nfdsmsgs 


readlist 


writelist 


exceptlist 


timeout 


A long integer that is evaluated in two halves, described as follows: 


Low 16 bits Contain the number of file descriptor bits to use from the 
mask value provided in the fdsmask[ ] array of the structure 
of type sellist for each of the operations. If this value is 
0x0000, no file-descriptor checking is performed. 


High 16 bits Not supported by AIX SNA Services/6000 and should be 
set to Ox0000. 


Points to a structure defined by the SELLIST( ) macro that specifies file 


descriptors for examination to see if they are ready for reading or receiving 
data. 


Points to a structure defined by the SELLIST( ) macro that specifies file 
descriptors for examination to see if they are ready for writing or sending 
data. Do not use this structure with SNA Services. 


Points to a structure defined by the SELLIST( ) macro that specifies file 
descriptors for examination to see if they have an exception condition 
pending. 


Points to a structure of type timeval that indicates the maximum number of 
seconds or microseconds to wait for the selection to complete. If this value 
is 0, the operation waits indefinitely. For polling, this value should be 
nonzero, pointing to a zero-valued structure. 
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Return Values 
When the subroutine completes successfully, it returns an integer value. The integer is 
evaluated in two halves: 


Low 16 bits This half contains the total number of file descriptors that satisfied the 
selection criteria (for all requested operations: read, write, and exception). 


High 16 bits Not supported by SNA Services. 


In addition, the SELECT operation modifies the sellist structures to indicate which file 
descriptors were selected: 


e Selected file descriptor bits are set to 1. 
e Not selected file descriptor bits are set to 0. 


If the time limit runs out, the subroutine returns a value of 0. If an error occurs, the ioctl 
subroutine returns a value of —1. In either case, the subroutine sets the errno global variable 
to indicate the error. 


Error Codes 
The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. 


EBADF One of the bit masks specified an invalid file descriptor. 


EINTR A signal interrupted the subroutine before it found any of the selected 
events, or the time limit ran out. 


Files 
/usr/include/sys/times.h 
Defines constants and structures used by the AIX operating system. 
/usr/include/sys/select.h 
Defines constants and structures used by the AIX operating system. 


Related Information 
The select subroutine. 
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select Subroutine for Generic SNA 


Purpose 

Examines a set of file descriptors. 
Syntax 

#include <sys/time.h> 

#include <sys/select.h> 

int select(nfdsmsgs, readlist, writelist, exceptlist, timeout) 

ulong nfdsmsgs; 

void *readilist, 

void *writelist, 

void *exceptlist, 

struct timeval *timeout, 
Description 


The select subroutine examines a set of resource IDs (file descriptors) to determine how 
many of the indicated resources: 


e Are available for reading or receiving data 
e Are available for writing or sending data (not supported by AIX SNA Services/6000) 
e Have an outstanding exception condition. 


The Generic SNA device driver supports the select (data received) and the select 
(exception condition). The select (write available) condition will always be satisfied because 
the Generic SNA device driver does not support the writelist parameter. 


The select (exception condition) results from one of the following: 
e INOP received from the PU Services of AIX SNA Services/6000. 
e Hierarchical_Reset received from the PU Services of AIX SNA Services/6000. 


After the select subroutine completes successfully, the application may issue a read 
subroutine to get the exception condition (returned by the errno of the read subroutine). 


A timeout value is also provided to prevent the operation from waiting for a long response 
time. If the nfdsmsgs parameter is a value of 0, the select subroutine acts as a timer and 
returns after the time period specified in the timeval structure. 


The read, write, and exception events are described with an unnamed structure, which is 
defined by a macro in the /usr/include/sys/select.h header file. This macro is defined as 
follows: 


#define SELLIST (F,M) 
struct 


_ 
int fdsmask[F]; 
int msgids[M]; 
}; 
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The additional parameters have the following meanings: 


fdsmask[F] 


msgids[M] 


Specifies an array of int values that is used as a continuous stream of bits. 
Each long value contains 32 bits, so that the first array member contains 
bits 0 through 31, the second array member contains bits 32 through 63, 
etc. The bit number plus one corresponds to the file descriptor that it 
represents (that is, bit 35 represents file descriptor 36). The SELECT 
operation examines all file descriptors up to the limit specified in the 
nfdsmsgs parameter for the condition corresponding to this structure (read, 
write or exception). When the subroutine returns, it sets the bits in this 
structure that represent the file descriptors that satisfied the examination to 
a value of 1. To disable a file descriptor checking for an operation, set all 
members of this array to a value of 0. 


Specifies an array of int values. Each long value is a message queue 
identifier that specifies a message queue to be examined. The SELECT 
operation examines the message queues for each ID up to the number of 
IDs indicated by the limit specified in the nfdsmsgs parameter for the 
condition corresponding to this structure (read, write or exception). When 
the subroutine returns, it sets all members of this array whose queues do 
not satisfy the examination to a value of —1. To disable message queue 
checking for an operation, set all members of this array to a value of —1. 


Message queue checking is not supported by AIX SNA Services/6000 and should be 
disabled by setting all members of this array to a value of OxFFFFFFFF. The value provided 
in the nfdsmsgs parameter determines the size that must be given to the fdsmask/[F] and 
msgids[M] arrays. 


The /usr/include/sys/select.h header file also defines two macros to help split nfdsmsgs 
and the return value into their component halves: 


NFDS(nfdsmsgs) 


Extracts the number of file descriptors. 


NMSGS(nfdsmsgs) 


Parameters 
nfdsmsgs 


readlist 


writelist 


Extracts the number of message queues. 


A long integer that is evaluated in two halves, described as follows: 


Low 16 bits Contains the number of file descriptor bits to use from the 
mask value provided in the fdsmask/F] array of the structure 
of type sellist for each of the operations. If this value is 
0x0000, no file descriptor checking is performed. 


High 16 bits Not supported by AIX SNA Services/6000 and should be 
set to 0x0000. 


Points to a structure defined by the SELLIST() macro that specifies file 
descriptors for examination to see if they are ready for reading or receiving 
data. 


Points to a structure defined by the SELLIST( ) macro that specifies file 
descriptors for examination to see if they are ready for writing or sending 
data. Do not use this structure with generic SNA device driver subroutines. 
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exceptlist Points to a structure defined by the SELLIST( ) macro that specifies file 
descriptors for examination to see if they have an exception condition 
pending. 

timeout Points to a structure of type timeval that indicates the maximum number of 


seconds or microseconds to wait for the selection to complete. If this value 
is 0, the operation waits indefinitely. For polling, this value should be 
non-zero, pointing to a zero—valued structure. 


Return Values 


When the subroutine completes successfully, it returns an integer value that is evaluated in 
two halves, described as follows: 


Low 16 bits Contains the total number of file descriptors that satisfy the selection 
criteria (for all requested subroutines: read, write, and exception). 


High 16 bits Contains the number of message queues that satisfy the selection criteria 
(for all requested subroutines: read, write, and exception). 


In addition, the SELECT operation modifies the sellist structures to indicate which file 
descriptors and message queues are selected: 


e Selected file descriptor bits are set to 1. 

e Unselected file descriptor bits are set to 0. 

e Selected message queue IDs remain unchanged. 
e Unselected message queue IDs are set to —1. 


If the time limit runs out, the subroutine returns a value of 0. If an error occurs, the ioctl 
subroutine returns a value of —1. In either case, it sets errno to indicate the error. 


Error Codes 


The call sets errno to a value that indicates the cause of any errors that occur, as shown in 
the following list: 


EBADF One of the bit masks specified an invalid file descriptor or message queue 
index. 

EINTR A signal interrupted the subroutine before it found any of the selected 
events, or the time limit ran out. 

EINVAL A bad timeout value was given in the timeout parameter. 

EAGAIN An internal storage allocation problem was detected. 

EFAULT A bad address value was passed in one of the parameters. 


Related Information 
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The close Subroutine for Generic SNA, open Subroutine for Generic SNA, read Subroutine 
for Generic SNA, write Subroutine for Generic SNA, ioctl Subroutine for Generic SNA. 


Developing Special AIX SNA Services/6000 Functions in Communications Programming 
Concepts. 
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snacise Subroutine 


Purpose 
Closes a connection. 


Syntax 


#include <luxsna.h> 


int snaclse(cid) 
int cid; 


Description 
The snaclse subroutine closes a connection specified by its connection ID. Deallocate all 
conversations on the connection before closing the connection (see the snadeal 
subroutine). If the conversations are not deallocated, closing the connection causes an 
abnormal end of the conversation. 


Parameter 


cid Specifies the variable that contains the connection ID returned by the 
snaopen subroutine. 


Return Values 
When the subroutine completes successfully, it returns a value of 0. If an error occurs, the 
subroutine returns a value of —1 and sets the errno global variable to indicate the error. 


Error Code | 
The subroutine sets the errno global variable to a value that indicates the cause of any 
errors that occur. The values that this variable can receive are shown below. Error Code 


Constants in Communications Programming Concepts contains a brief description of the 
error values for AIX SNA Services/6000. 


EBADF 
File 


/usr/include/luxsna.h 


Defines constants and structures used by AlX SNA Services/6000 
subroutines. 


Related Information 
The snaopen subroutine, snadeal subroutine. 
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snactl Subroutine 


Purpose 
Controls data transfer between local and remote transaction programs. 
Syntax 
#include <luxsna.h> 
int snactl(cid, request, arg, c_type) 
int cid; 
int request; 
int arg; 
char c_type; 
Description 
This subroutine provides control functions for transfer operations between a local and a 
remote transaction program. The control function is specified by the request parameter, and 
must be one of the integers (defined in the luxsna.h include file) explained in the following 
paragraphs: 
e ALLOCATE_LISTEN (LU 6.2 only) 
e CONFIRM 
e CONFIRMED 
e CP_STATUS (LU 6.2 only) 
e FLUSH 
e GET_ATTRIBUTE (LU 6.2 only) 
e GET_PARAMETERS (LU 6.2 only) 
e GET_STATUS (LUs 1, 2, and 3 only) 
e PREPARE_TO_RECEIVE 
e REQUEST _TO_SEND 
e SEND_ERROR 
e SEND_FMH (LU 1 only) 
e SEND_STATUS (LUs 1, 2, and 3 only). 
CONFIRM 
The CONFIRM request asks the remote transaction program to tell whether the last 
transmission was successfully received. The remote transaction program must respond with 
one of two snactl requests: CONFIRMED or SEND_ERROR. 
LU 6.2 
The program may use the CONFIRM request for the following special cases: 
e Directly following a snalloc function to determine if the allocation of the conversation was 
successful before sending data 
e Following transmission of data to the remote program to get an acknowledgment from the 
remote program. 
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For LU 6.2, the arg parameter specifies a pointer to a structure of type confirm_str, which 
contains additional input parameters for the request. Refer to the confirm_str structure for 
field descriptions. 


LUs 1, 2, and 3 


LU 1 uses the CONFIRM request to get an acknowledgement for data that it sent to the 
remote program. However, LUs 2 and 3 do not use this request for that purpose. The remote 
program must handle error recovery for the local LU 2 or 3 program. 


For LUs 1, 2, and 3, the arg parameter specifies a pointer to a structure of type confirm_str 
which contains additional parameters for the request. Refer to the confirm_str structure for 
field descriptions. 


CONFIRMED 


FLUSH 


The CONFIRMED request is a response to the CONFIRM request indicating that the remote 
site received the transmission without detecting any errors. This request cannot be used 
except in response to a CONFIRM request. 


This request can be used to create and send a positive response to the remote session to 
indicate the successful receipt of a command. 


For this request, the arg parameter specifies the resource ID. 


CP_STATUS requests information about the capabilities of the control point at the remote 
node. The request includes the resource ID, the rid parameter, returned from the 
ALLOCATE request. 


The remote node responds with its control point name and the session type, contention 
winner CONWINNER or contention loser CONLOSER. The remote node also returns a list 
of capabilities, each followed by a YES or NO, indicating whether the feature is supported. 


For this request, the arg parameter is a pointer to a structure of type cp_status. This 
structure contains the parameters that are sent and the parameters that are returned. Refer 
to the cp_str structure for field descriptions. 


The FLUSH request sends any information in the local LU send buffer to the remote LU. 
This function can be used on a basic conversation only. The LU normally buffers the data 
from snawrit functions until it has enough data to transmit. Using this request the local 
program forces the local LU to transmit the data in the buffer. The local program can use this 
request to decrease the delay required to get the data to the remote system. 


The arg parameter for this request is a pointer to a structure of type flush_str, which 
contains the input and output parameters for the request. Refer to the flush_str structure for 
field descriptions. 


GET_ATTRIBUTE 


The GET_ATTRIBUTE request gets information about the specified LU 6.2 conversation. 


The arg parameter for this request is a pointer to a structure of type attr_str, which contains 
the input parameter rid and receives the output information from the request. Refer to the 
attr_str structure for field descriptions. 
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GET_STATUS 


The GET_STATUS request gets information about the current link and session, as well as 
information from the BIND request for the LU-LU session. This information is used for LUs 
1, 2, and 3 only. 


The arg parameter for this request is a pointer to a structure of type gstat_str, which 


contains the the output status information from the request. Refer to the gstat_str structure 
for field descriptions. 


PREPARE TO RECEIVE 


The PREPARE_TO_RECEIVE request notifies the remote LU that the local LU needs to 


change the conversation direction so that the local LU can begin receiving from the remote 
LU. 


The arg parameter for this request is a pointer to a structure of type prep_str, which 


contains the input and output parameters for the request. Refer to the prep_str structure for 
field descriptions. 


REQUEST_TO_ SEND 


The REQUEST_TO_SEND request notifies the remote LU that the local LU needs to change 
the conversation direction so that the local LU can begin sending to the remote LU. The local 
program uses a readx subroutine to get the send indication from the remote program (in the 
what_control_rcvd field). When the local program receives this indication from the 
remote program, it enters the send state. 


For this request, the arg parameter specifies the resource ID. 


SEND ERROR 
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The SEND_ERROR request informs the remote transaction program that the local 


transaction program has detected an error in the information that it received from the remote 
program. 


The arg parameter for this request is a pointer to a structure of type erro_str, which contains 
the input parameters for the request. Refer to the erro_str structure for field descriptions. 


LU 6.2 
When this request is issued in send state, the LU: 
1. Flushes the local send buffer. 
2. Creates and sends an FMH7 request. 
When the FMH7 request is issued in receive state, the LU: 
1. Generates a negative response. 
. Purges all incoming data. 


2 
3. Waits for a send indication to arrive from the remote program. 
4. Creates an FMH7 request and sends it. 

5 


. Enters send state to send the error message. 
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LUs 1, 2, and 3 

When the FMH7 request is issued in send state, the LU: 
1. Flushes the send buffer. 

2. Sends a CANCEL request to the remote session. 
When this request is issued in receive state, the LU: 


1. Generates a negative response, using the sense_code parameter specified in the 
erro_ str structure. 


2. Purges all incoming data to the end of chain. 


The SEND_FMH request sends the FM header to the remote LU. Since the SEND_FMH 
request is used only by LU 1 support, it must be used on a basic conversation. 


The arg parameter for this request is a pointer to a structure of type fmh_str, which contains 
the input parameters for the request. Refer to the fmh_str structure for field descriptions. 


The application program must build the complete FM header to be sent. If more than one FM 
header is to be sent, the application must build all FM headers with the concatenation bit set 
within a contiguous area. The application program must also enforce concatenation and 
chaining rules. 


SEND_STATUS 


The SEND_STATUS request sends status information about the devices on the local 
session (LUs 1, 2, and 3, only) to the host program. This request can be used on a basic 
conversation only. When issued in send state, an LUSTAT is sent to the remote session, 
using the ID to indicate which device the LUSTAT is for. This request is used for LU1 LU-LU 
sessions only. 


The arg parameter for this request is a pointer to a structure of type stat_str, which contains 
the input parameters for the status request. Refer to the stat_str structure for field 
descriptions. 


Parameters 

cid Specifies the variable that contains the connection ID returned by the 
snaopen subroutine. 

request Specifies the function to be performed as defined in the luxsna.h include 
file. 

arg Specifies the variable that contains one of the following (varies with the 
function performed as specified in the request parameter): 
e The resource ID returned by the snalloc subroutine. 
e A pointer to a structure that contains additional input parameters for the 

requested function. 

c_type Specifies a character constant that indicates the conversation type: 
'B’ The request is performed on a basic conversation. 
mM’ The request is performed on a mapped conversation. 
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Return Values 


When the subroutine completes successfully, it returns a non-negative integer that is equal 
to 0 for most requests. However, when the CONFIRM and SEND_ERROR requests 
complete successfully, they return one of the following values: 


0 Successful completion, but did not receive a request to send. 


1 Successful completion and received a request to send from the remote 
transaction program. 


Additional information, if any, is stored in the structures provided by the specific request. If 


an error occurs, the subroutine returns a value of —1 and sets the errno global variable to 
indicate the error. 


Error Codes 
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The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive vary with the requested function as 
shown in the following table. Error Code Constants in Communications Programming 
Concepts contains a brief description of the following error values for AIX SNA 
Services/6000. 
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ERRNO VALUE 


CONFIRMED 


CONFIRM 


REQUEST TYPE 
















EBADF 
EINTR 
EINVAL 
ENOMEM 


ENXIO 
SNA_ALFN 
SNA_ALFR 
SNA_BOUNDARY 


SNA_CTYPE 


SNA_DEALPGM 
SNA_EXCEED 










SNA_MAPEXEC 
SNA_MAP_NOTFND 


SNA_NMAP 
SNA_NOCONN 
SNA_NOTPN 
SNA_NPIP 


SNA_NREC 
SNA_NRMDEAL 
SNA_NRREC 
SNA_NSES 


SNA_NSYC 
SNA_PGMDEAL 





GET_STATUS — 
GET_ATTR 
FLUSH 














SNA_PGMPURGE 
SNA_PNREC 


SNA_PNSYC 
SNA_PNTR 
SNA_PPURG 
SNA_PROTOCOL 


SNA PTR 
SNA_REN 














SNA_SPURG 
SNA_STATE 


SNA_SVCDEAL 
SNA_TIMDEAL 
SNA_WRGPIP 
SNA_NOTCP 


Figure 1. 































snactl 


PEEP_RECVUS 
CP_STATUS 
SEND_ERROR 
SEND_STATUS 
SEND_FMH 


RTS 














The snactl Subroutine Error Returns 
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File 
/usr/include/luxsna.h 
Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
Node Verification in Defining LU Type 6.2 Connection Characteristics in Communication 
Concepts and Procedures. 


The snaopen subroutine, snalloc subroutine. 
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snadeal Subroutine 


Purpose 


Syntax 


Deallocates the specified conversation from the transaction program. 


#include <luxsna.h> 


int snadeal(cid, ptr, c_type) 
int cid; 

struct deal_str *ptr, 

char c_type; 


Description 


The snadeal subroutine removes the allocation of the specified conversation from the local 
transaction program. Information about the deallocation is supplied in the structure of type 
deal_str pointed to by the ptr parameter. Refer to the deal_str structure for field 
descriptions. 


LU 6.2 


The snadeal subroutine ends the conversation but not the session. The LU resource 
manager determines whether to keep or end the session. 


Although a deallocation with a type field of local occurs in the general SNA specifications, 
do not use that type with AIX SNA Services/6000. The SNA device driver performs the local 
deallocation function when the device driver receives a deallocate request from the remote 
transaction program. The device driver then sets the what_control_rcvd field in the 
read_out structure to indicate the type of deallocation the device driver received from the 
remote program. See the snaread subroutine for an explanation of the read_out structure. 


LUs 1, 2, and 3 


Do not use the snadeal subroutine with an LU—LU session for either LUs 2 or 3. If used with 
these sessions, the subroutine returns with an SNA_STATE error. Using snadeal with an 
LU-LU session for LU 1 ends a bracket. 


Use the confirm _deallocate and normal_deallocate parameters only on an LU-LU 
session to indicate the end of a bracket. 


Do not use the following parameters: 
e confirm_deallocate retain 
e normal deallocate retain 


e confirm_deallocate on an SSCP-LU session 


- @ normal _deallocate on an SSCP-LU session. 


To deallocate an LU-LU session that has a corresponding SSCP-—LU session, use the 
snadeal subroutine to deallocate the SSCP-LU session. When the local transaction 
program issues a snadeal routine with type setto B’010’ (flush) for the SSCP—LU 


' session, the local LU issues an RSHUTD to request an UNBIND negotiation to terminate the 


LU-LU session. The local LU rejects all data from the host on the LU-LU session until it 
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receives the UNBIND request. The local LU rejects all data from the host on the SSCP-—LU 
session until that session is allocated to another application program. 


The host can issue an UNBIND request at other times to end the LU—LU session. When the 
UNBIND request occurs, the local program using the LU-LU session receives a return code 
of SNA_NSES that notifies this program of the session end. If the application uses a 
GET_STATUS request of the snactl subroutine, the returned status indicates that the 
session is not active. 


The local LU cannot issue a DACTLU request to end the SSCP-LU session. Therefore, the 
session remains active until the host ends it with aDACTLU, DACTPU or ACTPU request. In 
this case, the snadeal subroutine used on the SSCP-LU session removes the connection to 
the local program, but does not remove the SSCP-LU session itself. 


When used on an LU 1 LU—LU session, the snadeal subroutine ends a bracket. 


Parameters 
cid Specifies the variable that contains the connection ID returned by the 
snaopen subroutine. 
ptr Specifies a pointer to a structure that contains additional input parameters. 
c_type Specifies a character constant that indicates the conversation type: 
"B’ The request is performed on a basic conversation. 
‘M’ The request is performed on a mapped conversation. 


Return Values 


When the subroutine completes successfully, it returns a value of 0. If an error occurs, the 
subroutine returns a value of —1 and sets the errno global variable to indicate the error. 


Error Codes 
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The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 
Code Constants in Communications Programming Concepts contains a brief description of 
the error values for AIX SNA Services/6000. 


EBADF SNA_MAP SNA_PPURG 
EINTR SNA_NOCONN SNA_PROTOCOL 
EINVAL SNA_NOTPN SNA_PTR 
ENOMEM SNA_NPIP SNA_RFN 
SNA_ALFN SNA_NREC SNA_RFR 
SNA_ALFR SNA_NRMDEAL SNA_RREC 
SNA_BOUNDARY SNA_NRREC SNA_SNTR 
SNA_CTYPE SNA_NSYC SNA_SPURG 
SNA_INVACC SNA_PGMDEAL SNA_STATE 
SNA_MAPEXEC SNA_PNREC SNA_SVCDEAL 
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SNA_MAP_NOTFND SNA_PNSYC SNA_TIMDEAL 

SNA_NFMH SNA_PNTR SNA_WRGPIP 
File 

/usr/include/luxsna.h 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The snactl subroutine, snaopen subroutine, snalloc subroutine. 
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snalloc Subroutine 


Purpose 
Creates a session and conversation between two transaction programs. 


Syntax 


#include <luxsna.h> 


long snalloc(cid, allo_ptr, c_type) 
int cid; 

struct allo_str *a//o_ptr, 

char c_type; 


Description 
The snalloc subroutine allocates a session between the local LU and a remote LU. Then it 
allocates a conversation between the local transaction program and a remoie transaction 
program using the allocated session. The subroutine returns a resource ID to identify the 
conversation. Use this subroutine before using any other subroutine that refers to the 
conversation. 


The allo_ptr parameter is a pointer to a structure of type allo_str, which contains additional 
information for the subroutine. This structure contains a pointer to an additional structure 
pip str. Refer to the allo_str and pip_str structures for field descriptions. 


LU 6.2 


When this subroutine completes successfully, the local transaction program (the one that 


used this subroutine) is in the send state and the remote transaction program is in the 
receive state. 


If two LUs that are connected by a session try to allocate a conversation on that session at 
the same time, one of the LUs is successful and the other is not. Which LU is successful is 
determined by the BIND negotiation that occurred when the session was established. 


For two programs to reconnect to each other, the following events must occur: 


1. One program uses the snadeal subroutine with the deal_ flag parameter set to retain 
to deallocate the conversation. 


2. The program initiating the reconnection uses the snalloc subroutine with the type 
parameter set to reconnect. This action sends a reconnection request to the remote LU. 


3. The remote program completes the reconnection when it uses the snaread subroutine to 
receive information. 


LUs 1, 2, and 3 


When this subroutine completes successfully, the appropriate session (SSCP-—LU or LU—LU) 
is established and both LUs are in HDX contention state. The SSCP-LU session must be 
active and allocated before allocating the LU-LU session. Trying to allocate the LU-LU 
session before the SSCP—LU session results ina SNA_STATE error return from the snalloc 
subroutine. 


If an application program tries to allocate an SSCP-—LU session and the ACTLU request has 
not yet been received, the subroutine returns the SNA_NSES error code (session not active) 
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and does not allocate a session. If the application program then uses the GET_STATUS 
request of the snactl subroutine, the returned status shows that the SSCP-LU session is 
inactive. 


If an application program tries to allocate an LU-LU session, but the BIND request for that 
session has not yet been received, the result depends upon whether the LU names for both 
LUs of the requested session are specified in the connection profile: 


e LU Names Specified: The local LU sends an INIT_SELF request on the SSCP-LU 
session to request the needed BIND negotiation. When the LU receives and accepts the 
BIND request, it then completes the requested allocation of the LU—LU session. 


e LU Names Not Specified: The LU-LU session cannot be allocated. The subroutine 
returns the SNA_NSES error code to indicate that the session is not active. 


lf the host bid for the session, the snalloc subroutine rejects the bid. See the ALLOCATE 
section of the ioctl subroutine for more information. 


Parameters 


cid Specifies the variable that contains the connection ID returned by the 
snaopen subroutine. 


allo_ptr Specifies a pointer to the structure that contains additional input parameters 
for the subroutine. If you do not provide this information, the subroutine uses 
the values contained in the remote transaction profile specified in the 
snaopen subroutine. If no remote transaction profile is specified in the 
snaopen subroutine, the first remote transaction profile in the connection 
profile associated with the snaopen subroutine is used. 


c_type Specifies a character constant that indicates the conversation type: 


'B! The request is performed on a basic conversation. When 
the type field of the allo_str structure is B’11’ (see 
type), this parameter indicates that a basic conversation is 
to be reconnected. 


‘mM’ The request is performed on a mapped conversation. When 
the type field of the allo_str structure is B’11’ (see 
type), this parameter indicates that a mapped conversation 
is to be reconnected. 


Return Values 
When the subroutine completes successfully, it returns a positive integer that indicates the 


resource ID for the conversation. If an error occurs, the subroutine returns a value of —1 and 
sets the errno global variable to indicate the error. 
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Error Codes 
The subroutine sets the errno global variable to a value that indicates the cause of any 
errors that occur. The values that this variable can receive are shown in the following list. 
Error Code Constants in Communications Programming Concepts contains a brief 
description of the error values for AIX SNA Services/6000. 


EBADF SNA_LUNSYC — ~—SNA_NRESTART 
EINTR SNA_NIMMED SNA_NSYC 
ENOMEM SNA_NOCONN SNA_PROTOCOL 
SNA_ALFN SNA_NOMODE SNA_RFN 
SNA_ALFR SNA_NOTPN SNA_RFR 
SNA_LUNREC — SNA_NREC SNA_STATE 


File 
/usr/include/luxsna.h 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The snadeal subroutine, snaopen subroutine, and snaread subroutine. 
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snaopen Subroutine 


Purpose 
Opens an SNA connection. 
Syntax 
#include <luxsna.h> 
int snaopen(resource) 
char *resource; 
Description 
The snaopen subroutine initializes a connection to a resource described in a specified 
connection profile. You must use the snaopen subroutine before using any other SNA 
subroutine for a particular connection. 
Parameters 
The resource parameter consists of: 
con Specifies the connection profile name of the resource to be opened. 
tpn Specifies the remote transaction profile name to be used in place of the 


remote transaction profile name found in the connection profile. The ton 
parameter is optional. If you do not specify this parameter, the snaopen 
subroutine uses the remote transaction profile name found in the connection 
profile. If you specify this parameter, separate it from the connection profile 
name with a / (slash). Remote transaction profiles are used in LU 6.2 only. 
Do not supply this parameter for LUs 1, 2, or 3. 


Return Values 
When the subroutine completes successfully, it returns a positive integer that specifies the 


connection ID (cid) for the connection. If an error occurs, the subroutine returns a value of —1 
and sets the errno global variable to indicate the error. 


Error Codes 
The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 
Code Constants in Communications Programming Concepts contains a brief description of 
the error values for AIX SNA Services/6000. 


EEXIST ENOTDIR EROFS 
EINVAL ENXIO EMFILE 
ENOENT EACCES ETXTBSY 
ENOMEM EISDIR EFAULT 
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File 
/usr/include/luxsna.h 
Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The snaclse subroutine. 


7-74 Base Operating System Reference 


snaread 


snaread Subroutine 


Purpose 
Receives information from a specified conversation. 
Syntax 
#include <luxsna.h> 
int snaread (cid, data, length, rid, fill, output_ptr, c_type) 
int cid; 
char *data; 
int length; 
int rid; 
int fill; 
struct read_out *output_ptr, 
char c_type; 
Description 
The snaread subroutine waits for information to arrive on the specified conversation and 
then receives the information. If information is already available, the program receives it 
without waiting. The information can be data, conversation status, or a request for 
confirmation. 
The program uses this subroutine when in the send state, causing the following actions to 
occur: 
1. The LU flushes its send buffer, sending all buffered information and the send indication to 
the remote program, 
2. The local program enters the receive state and waits for information from the remote 
program. 
When trying to read from a conversation that has no data available, the state of the 
O_NDELAY flag (see the open or fentl subroutine) determines what happens to the read 
operation: 
set The read returns a value of 0 and sets the what_data_rcvd field (in the 
ext_io_str structure) to indicate whether the received data was complete. 
clear The read is blocked until data becomes available. 
To perform a read_any function, the O_NDELAY flag must be set on. 
LUs 1, 2,and 3 
Use only the buffer value for the fill option. 
Parameters 


cid Specifies the variable that contains the connection ID returned by the 
snaopen subroutine. 


data Specifies a pointer to the buffer area into which the data will be read. 
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length 


rid 


output_ptr 


c_type 


fill 


buffer (0) 


11 (1) 


Specifies the variable that contains a value indicating the maximum number 
of bytes of data to be received. This value cannot be larger than 32,764 
(32K — 4) bytes. 


Specifies the variable that contains the resource ID returned by the snalloc 
subroutine that allocated the resource to be read. If you do not specify a 
value for the rid parameter(a null value), the subroutine performs a 
read_any operation. It reads the first resource that is allocated to the 
program and that has data to be read. 


Specifies a pointer to a structure of type read_out, which contains space for 
the output parameters from this subroutine. 


Specifies a character constant that indicates the conversation type: 
'B’ The request is performed on a basic conversation. 
'M’ The request is performed on a mapped conversation. 


Specifies whether the program receives data in terms of the logical record 
format of the data. If you do not specify one of the two following values, the 
program uses a value of buffer. Always use a value of buffer for LUs 1, 2, 
and 3. 


Specifies that the program receives data without regard to the logical record 
format of the data. 


Specifies that the program receives one complete logical record or a logical 
record that has been truncated to the length specified in the /ength 
parameter of this subroutine. This value is used for LU 6.2 basic 
conversations only. 


The output_ptr parameter for this request is a pointer to a structure of type read_out, which 
receives the information produced by this subroutine. Refer to the read_out structure for 
field descriptions. 


Return Values 
When the subroutine completes successfully, it returns a positive integer that indicates the 
number of bytes received and places received data in the user buffer pointed to by the data 
parameter. Additional information is stored in the read_out structure. If an error occurs, the 
subroutine returns a value of —1 and sets the errno global variable to indicate the error. 
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If an interrupt occurs while the subroutine is processing, it returns the number of bytes that 
have already been transferred to the user buffer. If no data has been moved when the 
interrupt occurs, it returns a value of —1 and sets the errno global variable to EINTR. 
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Error Codes 


snaread 


The subroutine sets the errno global variable to a value that indicates the cause of any 
errors that occur. The values that this variable can receive are shown in the following list. 
Error Code Constants in Communications Programming Concepts contains a brief 
description of the error values for AIX SNA Services/6000. 


EBADF 

EINTR 

EINVAL 
ENOMEM 
SNA_ALFN 
SNA_ALFR 
SNA_BOUNDARY 
SNA_CTYPE 
SNA_EC 
SNA_INVACC 
SNA_NFMH 
SNA_MAPEXEC 
SNA_PNTR 


File 


/usr/include/luxsna.h 


SNA_NMAP 
SNA_NOCONN 
SNA_NOTPN 
SNA_NPIP 
SNA_NREC 
SNA_NRMDEAL 
SNA_NRREC 
SNA_NSES 
SNA_NSYC 
SNA_PGMDEAL 
SNA_PNREC 
SNA_PNSYC 
SNA_MAP_NOTFND 


SNA_PPURG 
SNA_PROTOCOL 
SNA_PTR 
SNA_RFN 
SNA_RFR 
SNA_RREC 
SNA_SNTR 
SNA_SPURG 
SNA_STATE 
SNA_SVCDEAL 
SNA_TIMDEAL 
SNA_WRGPIP 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 


The snactl subroutine, snadeal subroutine, snaopen subroutine, snalloc subroutine. 
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snawrit Subroutine 


Purpose 
Sends data to the remote transaction program. 


Syntax 


#include <luxsna.h> 


int snawrit (cid, data, length, rid, write_ptr, c_type) 
int cids 

char *data; 

int /ength; 

long rid; 

struct write_out *write_ptr, 

char c_type; 


Description 
The snawrit subroutine sends data to the remote transaction program. The local LU buffers 
all data to be transmitted until the buffers contain enough data to make a transmission block, 


or until the local transaction program forces the LU to transmit the data (see the snactl and 
snaread subroutines). 


Mapped Conversations 


For mapped conversations, the data to be sent consists of data records that contain only 
data and no record length parameter. The /ength parameter of the snawrit subroutine 
defines the length of the data record. In addition, each snawrit subroutine can send up to 
32,764 (32K — 4) bytes of data. Use several snawrit subroutines to send blocks of data that 
are longer than this limit. 


Basic Conversations for LU 6.2 


The data to be sent consists of logical records with a length that is determined by the local 
application program data format. The length is independent from the /ength parameter of this 
subroutine. A complete logical record contains the 2-byte 11 field plus all bytes of a logical 
record from the local application program. The 11 field contains the length of the complete 
logical record (the 11 field plus the logical record). Transmission of a logical record is not 
complete until the last byte of logical record is sent. Each snawrit subroutine can send up to 
32,764 (32K — 4) bytes of data. 


The local program must finish sending a logical record before using any of the following 
subroutines: 


e snactl with a CONFIRM request 

e snacti with a PREPARE_TO_RECEIVE request 

e snaread 

e snadeal using a type field that is notB’010’ (indicating an abnormal end). 


Using any of these subroutines before the logical record transmission is complete, results in 
a bad return code from the subroutine. 
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Basic Conversations for LUs 1, 2 and 3 


The data to be sent consists of chain elements with a length that is determined by the 
maximum request/response unit size specified in the BIND or ACTLU image. 


Parameters 
cid 


data 


length 


rid 


write_ptr 


c_type 


Return Values 


Specifies the variable that contains the connection ID returned by the 
snaopen subroutine. 


Specifies a pointer to the buffer area from which the data will be sent. 


Specifies the variable that contains a value indicating the number of bytes of 
data to be sent. This value cannot be larger than 32,764 bytes (32K bytes 
minus 4 bytes). 


Specifies the variable that contains the resource ID returned by the snalloc 
subroutine. 


Specifies a pointer to the write_out structure. 
Specifies a character constant that indicates the conversation type: 
'B’ The request is performed on a basic conversation. 


mM’ The request is performed on a mapped conversation. 


When the subroutine completes successfully, it returns a positive integer that indicates the 
number of bytes sent. If an error occurs, the subroutine returns a value of —1 and sets the 
errno global variable to indicate the error. 


If an interrupt occurs while the subroutine is processing, it returns the number of bytes that 
have already been transferred to the network. If no data has been transferred when the 
interrupt occurs, it returns a value of —1 and sets the errno global variable to EINTR. 


Error Codes 


The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 
Code Constants in Communications Programming Concepts contains a brief description of 
the error values for AIX SNA Services/6000. 


EBADF 
EINTR 
EINVAL 
ENOMEM 
SNA_ALFN 
SNA_ALFR 
SNA_CTYPE 
SNA_INVACC 


SNA_NPIP SNA_PROTOCOL 
SNA_NREC SNA_PTR 
SNA_NRESTART SNA_RFN 
SNA_NRMDEAL SNA_RFR 
SNA_NRREC SNA_RREC 
SNA_NSES SNA_SHUT 
SNA_NSYC SNA_SNTR 
SNA_PGMDEAL SNA_SPURG 
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File 


SNA_NIMMED 
SNA_NOCONN 
SNA_NOMODE 
SNA_NOTPN 


LUs 1, 2, and 3 


SNA_PNREC 
SNA_PNSYC 
SNA_PNTR 

‘SNA_PPURG 


SNA_STATE 
SNA_SVCDEAL 
SNA_TIMDEAL 
SNA_WRGPIP 


An errno value of SNA_SHUT indicates that a shutdown request had been received. The 
snawrit subroutine failed because the transmission requires a new bracket and new 
brackets are not allowed when shutdown is active. This value occurs during an LU-LU 


session only. 


/usr/include/luxsna.h 
Defines constants and structures used by AIX SNA Services/6000 


Related Information 
The snact! subroutine, snadeal subroutine, snalloc subroutine, snaopen subroutine, 
snaread subroutine. 
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write Subroutine for SNA Services/6000 


Purpose 


Syntax 


Sends data to the remote transaction program. 


#include <luxsna.h> 


int write(fildes, data, length) 
int fildes; 

char *data; 

int /ength; 


Description 


Note: Use this subroutine for LU 6.2 applications that use the limited interface only. 


The write subroutine sends data to the remote transaction program. The local LU buffers all 
data to be transmitted until the buffers contain enough data to make a transmission block or 
until the local transaction program forces the LU to transmit the data (see the ioctl(FLUSH) 
subroutine). The write subroutine uses the first conversation if multiple conversations are 
active. 


Data sent by the write subroutine consists of logical records. The length of the logical 
records is not determined by the /ength parameter of this subroutine. A complete logical 
record contains the 2—byte 11 (logical length) field plus all bytes of a logical record from the 
local application program. The 11 field contains the length of the complete logical record (11 
field plus the logical record). Transmission of a logical record is not complete until the last 
byte of the logical record is sent. 


The local program must finish sending a logical record before using any of the following 
subroutines: 


e read 
e ioctl with any of the following: 
— CONFIRM request 
— PREPARE_TO_RECEIVE request 


— DEALLOCATE request using a type field that is notB’ 010° (indicating an abnormal 
end). 


Using any of these routines before the transmission is complete results in a return code from 
the routine that indicates that the local program has not finished sending a logical record. 


Parameters 


fildes Specifies the file descriptor returned by the open subroutine. 
data Specifies a pointer to the buffer area from which the data will be sent. 


length Specifies the variable that contains a value indicating the number of bytes of 
data to be sent. 
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- Return Values 


When the subroutine completes successfully, it returns a positive integer that indicates the 
number of bytes sent. If an error occurs, the routine returns a value of —1 and sets the errno 
global variable to indicate the error. 


lf the subroutine is interrupted by a signal, it returns the number of bytes that have already 
been transferred to the network. If no data has been moved when the interrupt occurs, it 
returns a value of —1 and sets the errno global variable to EINTR. 


Error Codes 


File 


The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 
Code Constants in Communications Programming Concepts contains a brief description of 
the error values for AIX SNA Services/6000. 


EBADF SNA_NPIP SNA_PROTOCOL 
EINTR SNA_NREC SNA_PTR 
EINVAL SNA_NRESTART SNA_RFN 
ENOMEM SNA_NRMDEAL SNA_RFR 
SNA_ALFN SNA_NRREC SNA_RREC 
SNA_ALFR SNA_NSES SNA_SHUT 
SNA_BOUNDARY SNA_NSYC SNA_SNTR 
SNA_CTYPE SNA_PGMDEAL SNA_SPURG 
SNA_INVACC SNA_PNREC SNA_STATE 
SNA_NIMMED SNA_PNSYC SNA_SVCDEAL 
SNA_NOCONN SNA_PNTR SNA_TIMDEAL 
SNA_NOMODE SNA_PPURG SNA_WRGPIP 
SNA_NOTPN 


/usr/include/luxsna.h 


Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
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The write subroutine. 


The ioctl subroutine for SNA Services/6000, open subroutine for SNA Services/6000, read 
subroutine for SNA Services/6000. 
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write Subroutine for Generic SNA 


Purpose 
Sends data to a file descriptor. 
Syntax 
#include <luxgsna.h> 
int write (fildes, data, length) 
int writex (fildes, data, length, ext) 
int fildes; 
char “data; 
int length; 
int ext 
Description 
The write subroutine sends normal sequenced data, exchange ID (XID) data, network data, 
or datagram data to a file descriptor. A write subroutine can be issued for normal data when 
the open subroutine has completed successfully. 
Parameters 
fildes Specifies the file descriptor returned by the open subroutine. 
data Specifies a pointer to the buffer area from which the data is sent. 
length Specifies the number of bytes of data to be sent. 
ext Ignored by generic SNA. 


Return Values 


Upon successful completion, the write subroutine returns a non—negative integer that 
indicates the number of bytes sent. If an error occurs, it returns a value of —1 and sets errno 


to indicate the error. 


Error Codes 


The call sets errno to a value which indicates the cause of any errors that occur, as shown 


in the following list: 
EBADF 

ENOMEM 
EFAULT 

EINTR 

EINVAL 


SNA_HIER_RESET 


An invalid file descriptor was specified. 
No write buffer available. 

An invalid address was specified. 

The write subroutine was interrupted. 
An invalid parameter was passed. 


Hierarchical Reset was received from AIX SNA 
Services/6000. 
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SNA_INOP An INOP was received from AIX SNA Services/6000. 


SNA_FAIL SNA system failure. SNA is not currently running. 


Related Information 


The close Subroutine for Generic SNA, open Subroutine for Generic SNA, read Subroutine 
for Generic SNA, ioctl Subroutine for Generic SNA, select Subroutine for Generic SNA. 


Developing Special AIX SNA Services/6000 Function in Communications Programming 
Concepts. 
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writex Subroutine for SNA Services/6000 


Purpose 


Syntax 


Sends data to the remote transaction program. 


#include <luxsna.h> 


int writex (fildes, data, length, ext) 


int fildes; 
char *data; 
int length; 
struct ext_io_str *ext; 


Description 


Note: Do not use this subroutine for programs that use the limited interface. 


The writex subroutine sends data to the remote transaction program. The local LU buffers 
all data to be transmitted until the buffers contain enough data to make a transmission, or 
until the local transaction program forces the LU to transmit the data (see the ioctl 
subroutine). 


The ext parameter points to a structure that contains additional input and output parameters 
for the writex subroutine. This same structure is used for the readx subroutine. This 
structure is defined in the luxsna.h include file. Refer to the ext_io_str structure for a 
description of the fields in this structure. The writex subroutine uses only the following fields: 


e priority 

e tpn_option 
e confirm 

e deallocate 
e deallo type 
e deallo flag 
e allocate 

e sess type 

e flush _flag 
e rq_to_snd_revd 
e rid 


e usrhdr_len 
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LU 6.2 


In addition to the data provided in the extended I/O structure ext_io_str, a program can 
supply header information about the data being sent. To do this, the program must: 


1. Define the length of the header information in the usrhdr_1en field of the ext_io_str 
structure. . 


2. Reserve consecutive space following the extended I/O structure (ext_io_str) for the 
header information. . . 


3. Store the header information in the contiguous space following the ext_io_str structure. 


4. Pass the extended I/O structure pointer (the ext parameter) in a writex subroutine. 


Data sent to the remote transaction program consists of logical records. The length of the 
logical records is not determined by the /ength parameter of this subroutine. A complete 
logical record contains the 2—byte 11 (logical length) field plus all bytes of a logical record 
from the local application program. The 11 field contains the length of the complete logical 
record (11 field plus the logical record). Transmission of a logical record is not complete uniii 
the last byte of the logical record is sent. 


The local program must finish sending a logical record before using any of the following 
subroutines: 


e read 
e ioctl with any of the following: 
— CONFIRM request 
— PREPARE_TO_RECEIVE request 


— DEALLOCATE request, using a type field that is not B&ssq.010&ssq. (indicating an 
abnormal end). 


Using any of these routines before the transmission is complete results in a bad return code 
from the routine that indicates that the local program has not finished sending a logical 
record. 


LUs 1, 2, and 3 


The data to be sent consists of chain elements whose length is determined by the maximum 
request/response unit size specified in the BIND or ACTLU request. 


If an error (negative response) occurs during the write, the subroutine sets the errno global 
variable to SNA_PPURG and sets the sense_code field to indicate the sense data received 
in the negative response. 


If the host bids for a session, a writex subroutine with the allocate bit on rejects the host bid 
and any data associated with the bid. For additional information, refer to the ALLOCATE 
section of the ioctl and readx subroutines. 


Parameters 
fildes Specifies the variable that contains the file descriptor returned by the open 
subroutine. 
data Specifies a pointer to the buffer area from which the data will be sent. 
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ext 


Return Values 


writex 


Specifies the variable that contains a value indicating the number of bytes of 
data to be sent. 


Specifies a pointer to an extended I/O structure of type ext_io_str. The 

ext_io_str structure allows the user to combine functions into one routine. 
You can use the writex(ALLOCATE and DEALLOCATE) functions on one 
routine. This structure type is defined in the luxsna.h include file. See the 
ext_io_str structure. 


When the subroutine completes successfully, it returns a positive integer that indicates the 
number of bytes sent. If an error occurs, the routine returns a value of —1 and sets the errno 
global variable to indicate the error. 


If an interrupt occurs while the subroutine is processing, it returns the number of bytes that 
have already been transferred to the network. If no data has been moved when the interrupt 
occurs, it returns a value of -1 and sets the errno global variable to EINTR. 


Error Codes 


The subroutine sets the errno global variable to a value to indicate the cause of any errors 
that occur. The values that this variable can receive are shown in the following list. Error 

Code Constants in Communications Programming Concepts contains a brief description of 
the error values for AIX SNA Services/6000. 


EBADF 
EINTR 
EINVAL 
ENOMEM 
SNA_ALFN 
SNA_ALFR 


SNA_BOUNDARY 
SNA_CTYPE 
SNA_INVACC 
SNA_NIMMED 
SNA_NOCONN 
SNA_NOMODE 
SNA_NOTPN 


SNA_NPIP 
SNA_NREC 
SNA_NRESTART 
SNA_NRMDEAL 
SNA_NRREC 
SNA_NSES 
SNA_NSYC 
SNA_PGMDEAL 
SNA_PNREC 
SNA_PNSYC 
SNA_PNTR 
SNA_PPURG 


SNA_PROTOCOL 
SNA_PTR 
SNA_RFN 
SNA_RFR 
SNA_RREC 
SNA_SHUT 
SNA_SNTR 
SNA_SPURG 
SNA_STATE 
SNA_SVCDEAL 
SNA_TIMDEAL 
SNA_WRGPIP 
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File 
/usr/include/luxsna.h 
Defines constants and structures used by AIX SNA Services/6000 
subroutines. 


Related Information 
The writex subroutine. 


The readx subroutine for SNA Services/6000, ioct! subroutine for SNA Services/6000, open 
subroutine for SNA Services/6000, snawrit subroutine for SNA Services/6000. 
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accept 


accept Subroutine 


Purpose 
Accepts a connection on a socket to create a new socket. 
Syntax 
#include <sys/types.h> 
#include <sys/socket.h> 
int accept (Socket, Address, AddressLength) 
int Socket; 
struct sockaddr *Address; 
int *AddressLength; 
Description 
The accept subroutine extracts the first connection on the queue of pending connections, 
creates a new socket with the same properties as the specified socket, and allocates a new 
file descriptor for that socket. 
If the listen queue is empty of connection requests, the accept subroutine: 
e Blocks a calling socket of the blocking type until a connection is present. 
e Returns an EWOULDBLOCK for sockets marked nonblocking. 
The accepted socket cannot itself accept more connections. The original socket remains 
open and can accept more connections. 
Parameters 
Socket Specifies a socket created with the socket subroutine, bound to an address 
with the bind subroutine, and that has issued a successful call to the listen 
subroutine. 
Address Specifies a result parameter that is filled in with the address of the 


connecting entity as known to the communications layer. The exact format 
of Address is determined by the domain in which the communication occurs. 


AddressLength Specifies a parameter that initially contains the amount of space pointed to 
by the Address parameter. Upon return, the parameter contains the actual 
length (in bytes) of the address returned. The accept subroutine is used 
with SOCK_STREAM socket types. 


Return Values 


Upon successful completion, the accept subroutine returns the nonnegative socket 
descriptor of the accepted socket. 


If the accept subroutine fails, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable ernno. 
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Error Codes 
The accept subroutine fails if one or more of the following are true: 


EBADF The Socket parameter is not valid. 

ENOTSOCK The Socket parameter refers to a file, not a socket. 

EOPNOTSUPP The referenced socket is not of type SOCK_STREAM. 

EFAULT The Address parameter is not in a writable part of the user address 
space. 

EWOULDBLOCK The socket is marked as nonblocking, and no connections are 


present to be accepted. 


Examples 


1. As illustrated in the following program fragment, once a socket is marked as listening, a 
server process may accept a connection: 


struct sockaddr_in from; 


fromlen = sizeof(from); 
newsock = accept(socket, (struct sockaddr*)&from, &fromlen) ; 


2. The Accepting a UNIX Stream Connection program fragrment illustrates the use of the 
accept subroutine. 


Implementation Specifics 
The accept subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the accept subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/netinet/in.h Contains Internet constants and structures. 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and 


contains buffer queues. 
/ustr/include/sys/types.h | Contains unsigned data types. 


Related Information 


Other socket creation and connection subroutines are the bind subroutine, connect 
subroutine, listen subroutine, select subroutine, and socket subroutine. 


Sockets Overview, Understanding Socket Creation, and Binding Names to Sockets in 
Communications Programming Concepts. 
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bind Subroutine 


Purpose 
Binds a name to a socket. 
Syntax 

#include <sys/types.h> 

#include <sys/socket.h> 

#include <netinet/in.h> 

int bind (Socket, Name, NameLength) 

int Socket; 

struct sockaddr *Name; 

int NameLength 

Description 

The bind subroutine assigns a Name to an unnamed socket. Sockets created by the socket 

subroutine are unnamed; they are identified only by their address family. Subroutines that 

connect sockets either assign names or use unnamed sockets. 

An application program can retrieve the assigned socket name with the getsockname 

subroutine. 

Parameters 

Socket Specifies the socket descriptor (an integer) of the socket to be 
bound. 

Name Points to an address structure that specifies the address to which 
the socket should be bound. The /sys/socket.h file defines the 
sockaddr address structure. The sockaddr structure contains an 
identifier specific to the address format and protocol provided in the 
socket subroutine. 

NameLength Specifies the length of the socket address structure. 


Return Values 
Upon successful completion, the bind subroutine returns a value of 0 (zero). 


If the bind subroutine fails, the subroutine handler performs the following actions: 
e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable errno 


Error Codes 
The bind subroutine fails if any one of the following errors occurs: 


EBADF The Socket parameter is not valid. 


ENOTSOCK The Socket parameter refers to a file, not a socket. 
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Examples 


EADDRNOTAVAIL The specified address is not available from the local 
machine. 

EADDRINUSE The specified address is already in use. 

EINVAL The socket is already bound to an address. 

EACCESS The requested address is protected, and the current user 
does not have permission to access it. 

EFAULT The Address parameter is not in a writable part of the 
UserAddress space. 


1. The following program fragment illustrates the use of the bind subroutine to bind the 


name “/tmp/zan/” to a UNIX domain socket. 


#include <sys/un.h> 


struct sockaddr_un.addr 


strcepy(addr.sun_path, “/tmp/zan/"); 
addr.sun_family = AF_UNIX; 
bind(s,(struct sockaddr*)&addr, strlen(addr.sun_path)+ 


sizeof (addr.sun_family) ); 


. The Reading UNIX Domain Datagrams Example Program fragrment illustrates the use of 


the bind subroutine. 


Implementation Specifics 


Files 


The bind subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the bind subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


/usr/include/netinet/in.h Contains internet constants and structures 
definitions. 

/usr/include/sys/socket.h Contains socket definitions. 

/usr/include/sys/socketvar.h Defines the kernel structure per socket and 


contains buffer queues. 


/usr/include/sys/types.h Contains definitions of unsigned data types. 
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Related Information 


Other socket creation and connection subroutines are the connect subroutine, listen 
subroutine, and socket subroutine. 


The subroutine to retrieve the socket name is the getsockname subroutine. 


Sockets Overview, Understanding Socket Connections, Binding Names to Sockets in 
Communications Programming Concepts. 
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connect Subroutine 


Purpose 
Connects two sockets. 
Syntax 

#include <sys/types.h> 

#include <sys/socket.h> 

#include <netinet/in.h> 

int connect (Socket, Name, NameLength) 

int Socket; 

struct sockaddr *Name; 

int NameLength; 

Description 

The connect subroutine requests a connection between two sockets. The kernel sets up 

the communications links between the sockets; both sockets must use the same address 

format and protocol. 

lf a connect subroutine is issued on an unbound socket, the system automatically binds the 

socket. 

The connect subroutine performs a different action for each of the following two types of 

initiating sockets: 

e Ifthe initiating socket is SOCK_DGRAM, then the connect subroutine establishes the 
peer address. The peer address identifies the socket where all datagrams are sent on 
subsequent send subroutines. No connections are made by this connect subroutine. 

e If the initiating socket is SOCK_STREAM, then the connect subroutine attempts to make 
a connection to the socket specified by the Name parameter. Each communication space 
interprets the Name parameter differently. 

Parameters 
Socket Specifies the unique name of the socket. 
Name Specifies the address of target socket that will form the other end of 


the communications line. 
NameLength Specifies the length of the address structure. 
Return Value 
Upon successful completion, the connect subroutine returns a value of 0 (zero). 


If the connect subroutine fails, the system handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable errno 
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Error Codes 
The connect subroutine fails if any one of the following errors occurs: 


EBADF The Socket parameter is not valid. 

ENOTSOCK The Socket parameter refers to a file, not a socket. 

EADDRNOTAVAIL The specified address is not available from the local 
machine. 

EAFNOSUPPORT The addresses in the specified address family cannot be 
used with this socket. 

EISCONN The socket is already connected. 

ETIMEDOUT The establishment of a connection timed out before a 


connection was made. 


ECONNREFUSED The attempt to connect was rejected. 

ENETUNREACH No route to the network or host is present. 

EADDRINUSE The specified address is already in use. 

EFAULT The Address parameter is not in a writable part of the user 


address space. 


EWOULDBLOCK The socket is marked nonblocking, the connection cannot 
be immediately completed. The application program can 
select the socket for writing during the connection process. 


Examples 
1. The following program fragment illustrates the use of the connect subroutine by a client 
to initiate a connection to a server’s socket. 


struct sockaddr_un server; 


connect(s,(struct sockaddr*)&server, strlen(server.sun_path)+ 
sizeof(server.sun family) ); 


2. The Initiating a UNIX Stream Connection program fragrment illustrates the use of the 
connect subroutine. 


Implementation Specifics 
The connect subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the connect subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/netinet/in.h Contains internet constants and structures 
' definitions. 
/usr/include/sys/socket.h Contains socket definitions. 
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/usr/include/sys/socketvar.h Defines the kernel structure per socket and 
contains buffer queues. 


/usr/include/sys/types.h Contains definitions of unsigned data types. 


Related Information 


Other socket creation subroutines are the accept subroutine, bind subroutine, and socket 
subroutine. 


Socket information retrieval and transmission subroutines are the getsockname subroutine, 
select subroutine, and send subroutine. 


Sockets Overview, Understanding Socket Connections in Communications Programming 
Concepts. 
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dn_comp Subroutine 


Purpose 
Compresses a domain name. 


Library 
(libc.a) 


Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int dn_comp (ExoDomNam, CompDomNam, Length, 
DomNamPtr, LastDomNamPth, 

u_char *ExoDomNam, *CompDomNam; 

int Length; 

u_char **DomNamPrrs, ** LastDomNamPrtr, 


Description 
The dn_comp (domain name compression) subroutine compresses a domain name to 
conserve space. When compressing names, the client process must keep a record of 
suffixes that have appeared previously. The dn_comp subroutine compresses a full domain 
name by comparing suffixes to a list of previously used suffixes and removing the longest 
possible suffix. 


The dn_comp compresses the domain name pointed to by the ExpandedDomNam 
parameter and stores it in the area pointed to by the CompDomNam parameter. The 
dn_comp subroutine inserts labels into the message as the name is compressed. The 
dn_comp subroutine also maintains a list of pointers to the message labels and updates the 
list of label pointers. 


e Ifthe value of DomNamPitris NULL, the dn_comp subroutine does not compress any 
names. The dn_comp subroutine translates a domain name from ASCII to internal 
format without removing suffixes (compressing). Otherwise, DomNamPrr is the address 
of pointers to previously compressed suffixes. 


e Ifthe LastDomNamPtr parameter is NULL, the dn_comp subroutine does not update the 
list of label pointers. 


The dn_comp subroutine is one of a set of subroutines that form the resolver. The resolver 
is a set of functions that perform a translation between domain names and network 
addresses. Global information used by the resolver subroutines resides in the _res data 
structure. The /include/resolv.h file contains the _res data structure definition. 


Parameters 
ExpDomNam Specifies the address of an expanded domain name. 


CompDomNam Points to an array containing the compressed domain 
name. 
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Length Specifies the size of the array pointed to by the 
CompDomNam parameter. 


DomNamPrtrs Specifies a list of pointers to previously compressed names 
in the current message. 


LastDomNamPtr ‘Points to the end of the array specified to by the 
CompDomNam parameter. 


Return Value 
Upon successful completion, the dn_comp subroutine returns the size of the compressed 
domain name. 


lf unsuccessful, the dn_comp subroutine returns a value of —1 (negative one) to the calling 
program. 

Implementation Specifics 
The dn_comp subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the dn_comp subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 

/etc/resolv.conf Defines name server and domain name structures, 
constants, and values. 

/usr/include/netinet/in.h Contains Internet constants and structures. 

/usr/include/arpa/nameser.h Defines Internet name server structures, constants, 
and values. 

/usr/include/resolv.h Contains global information used by the resolver 
subroutines. 

/usr/include/sys/types.h Contains definitions of unsigned data types. 


Related Information 
Domain name access subroutines are the res_init subroutine, res_mkquery subroutine, 
and res_send subroutine. 


Domain name translation subroutines are the dn_expand subroutine, dn_find subroutine, 
and dn_skipname subroutine. 


Byte stream and byte boundary retrieval subroutines are the _getshort subroutine, 
_getlong subroutine, putshort subroutine, and putlong subroutine. 


The named daemon. 


Sockets Overview, Understanding Domain Name Resolution in Communications 
Programming Concepts. 


Understanding Naming for TCP/IP in Communication Concepts and Procedures. 
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dn_expand Subroutine 


Purpose 
Expands a compressed domain name. 
Library 
(libc.a) 
Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 
int dn_expand (MessagePtr, EndOfMesOrig, 
CompDomNam, ExpandDomNam, Length) 
u_char *MessagePtr, *EndOfMesOrig; 
u_char *CompDomNam, *ExpandDomNam; 
int Length; 
Description 
The dn_expand subroutine expands a compressed domain name to a full domain name, 
converting the expanded names to all uppercase letters. A client process compress domain 
names to conserve space. Compression consists of removing the longest possible 
previously occuring suffixes. The dn_expand subroutine restores a domain name 
compressed by the dn_comp subroutine to its full size. 
The dn_expand subroutine is one of a set of subroutines that form the resolver. The 
resolver is a set of functions that perform a translation between domain names and network 
addresses. Global information used by the resolver subroutines resides in the _res data 
structure. The /include/resolv.h file contains the _res data structure definition. 
Parameters 
MessagePtr Specifies a pointer to the beginning of a message. 
EndOfMesOrig Points to the end of the original message that contains the 
compressed domain name. 
CompDomNam Specifies a pointer to a compressed domain name. 
ExpandDomNam Specifies a pointer to a buffer that holds the resulting 


expanded domain name. 


Length Specifies the size of the buffer pointed to by the 
ExpandDomNam parameter. 


Return Value 


Upon successful completion, the dn_expand subroutine returns the size of the expanded 
domain name. 
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If unsuccessful, the dn_expand subroutine returns a value of —1 (negative one) to the 
calling program. 


Implementation Specifics 


Files 


The dn_expand subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the dn_expand subroutine must be compiled with _bsd defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


/etc/resolv.conf Defines name server and domain name constants, 
structures, and values. 

/usr/include/netinet/in.h Defines Internet constants and structures. 

/usr/include/arpa/nameser.h Defines Internet name server constants, structures, 
and values. 

/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 
buffer queues. 

/usr/include/sys/types.h Contains definitions of unsigned data types. 


Related Information 
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Domain name access subroutines are the res_init subroutine, res_mkquery subroutine, 
and res_send subroutine. 


Domain name translation subroutines are the dn_comp subroutine, dn_find subroutine, 
and dn_skipname subroutine. 


Byte stream and byte boundary retrieval subroutines are the getshort subroutine, _getlong 
subroutine, putshort subroutine, and putlong subroutine. 


Sockets Overview, Understanding Domain Name Resolution in Communications 
Programming Concepts. 


Understanding Naming for TCP/IP in Communication Concepts and Procedures. 
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dn_find Subroutine 


Purpose 
Searches for an expanded domain name. 


Library 
(libc.a) 


Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


dn_find (ExpandDomNam, Message, DomNamPtrs, LastDomNamPtn 
char *ExpDomNam, * Message; 
char ** DomNamPrtrs, ** LastDomNamPtr, 


Description 
The dn_find (domain name find) subroutine searches for an expanded domain name from a 
list of previously compressed names. An expanded domain name is an one that is not 
compressed. If an expanded domain name is found, the dn_comp subroutine returns the 
offset from Message. An application program does not call the dn_find subroutine, directly. 
Instead, the dn_find subroutine is called indirectly by the dn_comp subroutine. 


The dn_find subroutine is one of a set of subroutines that form the resolver. The resolver is 
a set of functions that perform a translation between domain names and network addresses. 
Global information used by the resolver subroutines resides in the _res data structure. The 

/include/resolv.h file contains the _res data structure definition. 


Parameters 
ExpandDomNam Points to an expanded domain name. 


Message Points to the address of a domain name message that 
contains the name sought by the dn_find operation. 


DomNamPtrs Specifies an array of pointers to previously compressed 
names in the current message. 


LastDomNamPtr Points to the end of an array of pointers. The array is 
indicated by the DomNamPrtrs parameter. 


Return Values | 
Upon successful completion, the dn_find subroutine returns the offset from the Message 
parameter. 


If unsuccessful, the dn_find subroutine returns a value of —1 (negative one). 


Implementation Specifics 
The dn_find subroutine is part of AIX Base Operating System (BOS) Runtime. 
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All applications containing the dn_find subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 

/etc/resolv.conf Defines name server and domain name structures and 
constants. 

/usr/include/netinet/in.h Defines Internet constants and structures. 

/usr/include/arpa/nameser.h Defines Internet name server structures and 
constants. 

/usr/include/resolv.h Contains global information used by the resolver 
subroutines. 

/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 
buffer queues. 

/usr/include/sys/types.h Contains definitions of unsigned data types 


Related Information 
Domain name access subroutines are the res_init subroutine, res_mkquery subroutine, 
and res_send subroutine. 


Domain name translation subroutines are the dn_comp subroutine, dn_expand subroutine, 
and dn_skipname subroutine. 


Byte stream and byte boundary retrieval subroutines are the _getshort subroutine, 
_getlong subroutine, putshort subroutine, and putlong subroutine. 


The named daemon. 


Sockets Overview, Understanding Domain Name Resolution in Communications 
Programming Concepts 


Understanding Naming for TCP/IP in Communication Concepts and Procedures 
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dn_skipname Subroutine 


Purpose 
Skips over a compressed domain name. 
Library 
(libc.a) 
Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 
int dn_skipname (CompDomNam, EndOfMessage) 
u_char *CompDomNam; 
u_char *EndOfMessage; 
Description 
The dn_skipname subroutine skips over a compressed domain name. 
The dn_skipname subroutine is one of a set of subroutines that form the resolver, a set of 
functions that resolve domain names. Global information that is used by the resolver 
subroutines is kept in the _res data structure. The /include/resolv.h file contains the _res 
structure definition. 
Parameters 
CompDomNam Specifies a pointer to a compressed domain name. 
EndOfMessage Specifes a pointer to the end of the message string. 


Return Value 
Upon successful completion, the dn_skipname subroutine returns the size of 
CompDomNam. 


If the dn_skipname subroutine fails, the subroutine returns a —1 (negative one). 
Implementation Specifics 
The dn_skipname subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the dn_skipname subroutine must be compiled with _BSD 
defined. In addition, when applicable, all socket applications must include the BSD library 


libbsd. 
Files 
/etc/resolv.conf Defines name server and domain name structures, 
values, and constants. 
/usr/include/resolv.h Contains global information used by the resolver 
subroutines. 
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/usr/include/arpa/nameser.h Defines Internet name server structures, values, 
and constants. | 

/usr/include/sys/types.h Contains definitions of unsigned data types. 

/usr/include/netinet/in.h Defines Internet constants and structures. 


Related Information 
Domain name access subroutines are the res_init subroutine, res_mkquery subroutine, 
and res_send subroutine. 


Domain name translation subroutines are the dn_comp subroutine, dn_expand subroutine, 
and dn_find subroutine. 


Byte stream and byte boundary retrieval subroutines are the _getshort subroutine, 
_getlong subroutine, putshort subroutine, and putlong subroutine. 


Sockets Overview, Understanding Domain Name Resolution in Communications 
Programming Concepts. 
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endhostent Subroutine 


Purpose 
Ends retrieval of network host entries. 
Library 
(libc.a) 
Syntax 
#include <netdb.h> 
void endhostent ( ) 
Description 
The endhostent subroutine closes the /etc/hosts file. The /etc/hosts file is opened by 
either the gethostbyaddr or gethostbyname subroutine. 
Note: If a previous sethostent (STAYOPEN); routine has been performed and the 
STAYOPEN value does not equal 0 (zero), then the endhostent( ); routine will not 
close the /etc/hosts file. Also, the sethostent( ); routine does not indicate that it 
closed the file. A second sethostent (STAYOPEN); routine has to be issued with the 
STAYOPEN value equal to 0 (zero) in order for a following endhostent( ); routine to 
succeed. If this is not done, the /etc/hosts file closes on an exit( ); call. 
Example 


To close the /etc/hosts file: 
endhostent(); 
Implementation Specifics 
The endhostent subroutine is part of AIX Base Operating System (BOS) Runtime. 
All applications containing the endhostent subroutine must be compiled with _BSD defined. 


In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/hosts Contains the host name database. 
/usr/include/netdb.h Contains the network database structures. 


Related Information 
Additional host information retrieval subroutines are the gethostbyaddr subroutine, 
gethostbyname subroutine, and sethostent subroutine. 
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endnetent Subroutine 


Purpose 
Closes the networks file. 
Library 
libc.a 
Syntax 
#include <netdb.h> 
void endnetent ( ) 
Description 
The endnetent (end network entry) subroutine closes the /etc/networks file. Calls made to 
the getnetent, getnetbyaddr, or getnetbyname subroutines open the /etc/networks file. 
Note: Ifa previous setnetent (STAYOPEN) subroutine has been performed and the 
STAYOPEN value does not equal 0 (zero), then the endnetent subroutine will not 
close the /etc/networks file. Also, the setnetent subroutine does not indicate that it 
closed the file. A second setnetent (STAYOPEN); routine has to be issued with the 
STAYOPEN value equal to 0 (zero) in order for a following endnetent subroutine to 
succeed. If this is not done, the /etc/networks file closes on an exit call. 
Example 


To close the /etc/networks file: 
endnetent(); 
Implementation Specifics 
The endnetent subroutine is part of AIX Base Operating System (BOS) Runtime. 
All applications containing the endnetent subroutine must be compiled with _BSD defined. 


In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/networks Contains official network names. 
/usr/include/netdb.h Contains the network database structures. 


Related Information 
Additional network information retrieval subroutines are the getnetbyaddr subroutine, 
getnetbyname subroutine, getnetent subroutine, and setnetent subroutine. 


Sockets Overview, Understanding Network Address Translation in Communications 
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endprotoent Subroutine 


Purpose 
Library 


Syntax 


Closes the /etc/protocols file. 


(libe.a) 


void endprotoent ( ) 


Description 


Example 


The endprotoent (end protocol entry) subroutine closes the /etc/protocols file. 


Calls made to the getprotoent subroutine, getprotobyname subroutine, or 
getprotobynumber subroutine open the /etc/protocols file. An application program can 
use the endprotoent subroutine to close the /etc/protocols file. 


Note: Ifa previous setprotoent (STAYOPEN); routine has been performed and the 
STAYOPEN value does not equal 0 (zero), then the endprotoent; routine will not 
close the /etc/protocols file. Also, the setprotoent; routine does not indicate that it 
closed the file. A second setprotoent (STAYOPEN); routine has to be issued with 
the STAYOPEN value equal to 0 (zero) in order for a following endprotoent; routine 
to succeed. If this is not done, the /etc/protocols file closes on an exit; call. 


To close the /etc/protocols file: 


endprotoent(); 


Implementation Specifics 


File 


The endprotoent subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the endprotoent subroutine must be compiled with _BSD 
defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


letc/protocols Contains protocol names. 


Related Information 


Additional protocol information retrieval subroutines are the getprotobynumber subroutine, 
getprotobyname subroutine, getprotoent subroutine, and setprotoent subroutine. 


Sockets Overview, Understanding Network Address Translation in Communications 
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endservent Subroutine 


Purpose 
Closes the /etc/service file entry. 


Library 
(libc.a) 


Syntax 
#include <netdb.h> 


void endservent ( ) 


Description 
The endservent (end service entry) subroutine closes the /etc/services file. A call made to 
the getservent subroutine, getservbyname subroutine, or getservbyport subroutine 


opens the /etc/services file. An application program can use the endservent subroutine to 
close the /etc/services file. 


Note: Ifa previous setservent (STAYOPEN); routine has been performed and the 
STAYOPEN value does not equal 0 (zero), then the endservent( ); routine will not 
close the /etc/services file. Also, the setservent( ); routine does not indicate that it 
closed the file. A second setservent (STAYOPEN); routine has to be issued with the 
STAYOPEN value equal to 0 (zero) in order for a following endservent( ); routine to 
succeed. If this is not done, the /etce/services file closes on an exit( ); call. 


Example 
To close the /etc/services file: 


endservent (); 


Implementation Specifics 
The endservent subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the endservent subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/services Contains service names. 
/usr/include/netdb.h Contains network database structures. 


Related Information 
Additional service information retrieval subroutines are the getservbyname subroutine, 
getservbyport subroutine, getservent subroutine, and setservent subroutine. 


Protocol information retrieval subroutines are the endprotoent subroutine, 


getprotobynumber subroutine, getprotobyname subroutine, getprotoent subroutine, and 
setprotoent subroutine. 


Sockets Overview, Understanding Network Address Translation in Communications 
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getdomainname Subroutine 


Purpose 
Gets the name of the current domain. 


Syntax 


int getdomainname ( name, namelen ) 


char *name; 
int namelen; 


Description 
The getdomainname subroutine returns the name of the domain for the current processor 


as previously set by the setdomainname subroutine. The returned name is null-terminated 
unless insufficient space is provided. 


The purpose of domains is to enable two distinct networks that may have host names in 
common to merge. Each network would be distinguished by having a different domain name. 
At the current time, only the NIS and the sendmail command make use of domains 


Note: Domain names are restricted to 64 characters. 


Parameters 
name Specifies the domain name to be returned. 


namelen Specifies the size of the array pointed to by the name parameter. 


Return Values 
If the call suceeds, a value of 0 (zero) is returned. If the call fails, a value of —1 is returned 
and an error code is placed in the global location errno. 


Error Codes 
The following error may be returned by this subroutine: 
EFAULT The Name parameter gave an invalid address. 
Implementation Specifics 
The getdomainname subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getdomainname subroutine must be compiled with _BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


Related Information 
The gethostname subroutine, setdomainname subroutine, sethostname subroutine. 
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gethostbyaddr Subroutine 


Purpose 
Gets network host entry by address. 


Library 
(libc.a) 


Syntax 


#include<netdb.h> 


struct hostent *gethostbyaddr (Address, Length, Type) 
char *Aaddress; 
int Length, Type; 


Description 


The gethostbyaddr subroutine retrieves information about a host using the host address as 
a search key. 


The gethostbyaddr subroutine recognizes domain name servers as described in RFC883. 
If the file /etc/resolv.conf exists, the gethostbyaddr subroutine queries the domain name 
server. If the request to the domain name server times out, the gethostbyaddr subroutine 
checks the local /ete/hosts file. 


The gethostbyaddr returns a pointer to a hostent structure, which contains information 
obtained from the domain name server or which contains a field from a line in the /etc/hosts 
file. The hostent structure is defined in the netdb.h header file. 


Parameters 


Address Specifies a host address. The host address is passed as a character string 
and is assumed to be in dotted IP format. 


Length Specifies the length of host address. 


Type Specifies the domain type of the host address. This currently works only on 
address family: AF_INET. 


Return Values 
The gethostbyaddr subroutine returns a pointer to a hostent structure upon success. 
Note: The return value points to static data that is overwritten by subsequent calls. 


If an error occurs or if the end of the file is reached, the gethostbyaddr subroutine returns a 
NULL pointer and sets the h_errno variable to indicate the error. 


Error Codes 
The gethostbyaddr subroutine fails if any one of the following errors occurs: 


HOST_NOT_FOUND The host specified by the Name parameter is not found. 


TRY_AGAIN The local server does not receive a response from an 
authoritative server. Try again later. 
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NO_RECOVERY This error code indicates an unrecoverable error. 


NO_ADDRESS The requested Name parameter is valid but does not have 
an Internet address at the name server. 


Implementation Specifics 


Files 


The gethostbyaddr subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the gethostbyaddr subroutine must be compiled with BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


/etc/hosts Contains the host name data base. 
/usr/include/netdb.h Contains the network data base structures. 
letc/resolv.conf Contains the name server and domain name information. 


Related Information 


Additional host information retrieval socket subroutines are the endhostent subroutine, 
gethostbyname subroutine, and sethostent subroutine. 


Sockets Overview, Understanding Network Address Translation in Communications 
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gethostbyname Subroutine 


Purpose 
Gets network host entry by name. 
Library 
(libe.a) 
Syntax 
#include <netdb.h> 
struct hostent *gethostbyname (Name) 
char *Name; 
Description 
The gethostbyname subroutine retrieves host address and name information using a host 
name as a search key 
The gethostbyname subroutine recognizes domain name servers as described in RFC883. 
If the file /etc/resolv.conf exists, the gethostbyname subroutine queries the domain name 
server. If the request to the domain name server times out, the gethostbyname subroutine 
checks local /etc/hosts file. 
The gethostbyname subroutine returns a pointer to a hostent structure, which contains 
information obtained from a name server program or contains a field from a line in the 
/etc/hosts file. The hostent structure is defined in the netdb.h header file. 
Use the endhostent subroutine to close the /etc/hosts/ file or the TCP connection. 
Parameter 


Name Points to the host name. 


Return Values 


The gethostbyname subroutine returns a pointer to a hostent structure on success. 
Note: The return value points to static data that is overwritten by subsequent calls. 


If an error occurs or if the end of the file is reached, the gethostbyname subroutine returns 
a NULL pointer and sets h_ernno variable to indicate the error. 


Error Codes 
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The gethostbyname subroutine fails if any one of the following errors occur: 


HOST_NOT_FOUND The host specified by the Name parameter was not found. 

TRY_AGAIN The local server did not receive a response from an 
authoritative server. Try again later. 

NO_RECOVERY This error code indicates an unrecoverable error. 

NO_ADDRESS The requested Name is valid but does not have an Internet 


address at the name server. 
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Example 
1. The following program fragment illustrates the use of the gethostbyname subroutine to 
look up a destination host. 


hp=gethostbyname(argv[1]); 


if(hp = = NULL) { 
fprintf(stderr, “rlogin: %s: unknown host\n”, argv[1]}); 
exit(2); 

} 


Implementation Specifics 
The gethostbyname subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the gethostbyname subroutine must be compiled with _BSD 
defined. In addition, when applicable, all socket applications must include the BSD library 


libbsd. 

Files 
/etc/hosts Contains the host name data base. 
/etc/resolv.conf Contains the name server and domain name. 
/usr/include/netdb.h Contains the network data base structures. 


Related Information 
Additional host information retrieval routines are the gethostent subroutine, endhostent 
subroutine, gethostbyaddr subroutine, and sethostent subroutine. 
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gethostent Subroutine 


Purpose 
Retrieves a network host entry. 
Library 
(libe.a) 
Syntax 
#include <netdb.h> 
gethostent ( ) 
struct hostent *gethostent () 
Description 


The gethostent subroutine allows an application program to retrieve an entry from the 
/etc/host file. The gethostent subroutine opens the /etc/host file and performs a 
sequential read of each line in the file starting from the beginning of the file. Each 
subsequent gethostent subroutine call returns information for a different host. 


The gethostent subroutine returns a pointer to a hostent structure, which contains the 
equivalent fields for a host description line in the /etc/hosts file. The hostent structure is 
defined in the netdb.h header file. 


Use the endhostent subroutine to close the /etc/hosts file. 


Return Values 


Upon successful completion, the gethostent subroutine returns a pointer to a hostent 
Structure. 


Note: The return value points to static data that is overwritten by subsequent calls. 
If an error occurs or the end of the file is reached, the gethostent subroutine returns a 
NULL pointer. 


Implementation Specifics 
The gethostent subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the gethostent subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/hosts Contains the host name database. 
/usr/include/netdb.h Contains the network database structures. 


Related Information 
Additional host information retrieval subroutines are the gethostbyaddr subroutine, 
gethostbyname subroutine, and sethostent subroutine. 
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gethostid 


gethostid Subroutine 


Purpose 

Gets the unique identifier of the current host. 
Syntax 

int gethostid ( ) 
Description 


The gethostid subroutine allows a process to retrieve the 32-bit identifier for the current 
host. In most cases, the host ID is stored in network standard byte order and is a DARPA 
Internet address for the local machine. 


Return Value 
Upon successful completion, the gethostid subroutine returns the identifier for the current 
host. 


If the gethostid subroutine fails, the system handler performs the following functions: 

e Returns a value of —1 (negative one) to the calling program 

e Moves an error code, indicating the specific error, into the global variable errno 
Implementation Specifics 

The gethostid subroutine is part of AIX Base Operating System (BOS) Runtime. 

All applications containing the gethostid subroutine must be compiled with _BSD defined. 


In addition, when applicable, all socket applications must include the BSD library libbsd. 


Related Information | 
Socket subroutines to set and obtain host names and to set host IDs, respectively, are the 
gethostname subroutine, sethostname subroutine, and sethostid subroutine. 
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gethostname Subroutine 


Purpose 
Gets the name of the local host. 

Syntax 
int gethostname (Name, NameLength) 
char *Name; 
int NameLength; 

Description 
The gethostname subroutine retrieves the standard host name of the local host. If sufficient 
space is provided, the returned Name parameter is null-terminated. System host names are 
limited to MAXHOSTNAMELEN as defined in /usr/include/sys/param.h. The 
MAXHOSTNAMELEN value is set at 32. 
The gethostname subroutine allows a calling process to determine the internal host name 
for a machine on a network. 

Parameters 
Name Returns the address of an array of bytes where the host name is stored. 
NameLength Returns an integer that specifies the length of the Name array. 


Return Values 
Upon successful completion, the system returns a value of 0 (zero). 


If the gethostname subroutine fails, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 
e Moves an error code, indicating the specific error, into the global variable errno 


Error Codes 
The gethostname subroutine fails if the following is true: 


EFAULT The Name parameter or NameLength parameter gives an invalid address. 
Implementation Specifics 
The gethostname subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the gethostname subroutine must be compiled with _BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


Related Information 
Socket subroutines to obtain and set the host ID are the gethostid subroutine and 
sethostid subroutine. 


The socket subroutine to set the host name is the sethostname subroutine. 
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_getlong 


_getlong Subroutine 


Purpose 
Retrieves long byte quantities. 


Library 
(libe.a) 


Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


unsigned long _getlong (MessagePtn 
u_char *MessagePtr, 


Description 
The _getiong subroutine gets long quantities from the byte stream or arbitrary byte 
boundaries. 


The _getlong subroutine is one of a set of subroutines that form the resolver, a set of 
functions that resolves domain names. Global information that is used by the resolver 
subroutines is kept in the _res data structure. The /include/resolv.h file contains the _res 
structure definition. 


Parameters | 
MessagePtr Specifies a pointer into the byte stream. 


Return Value 
The _getlong subroutine returns an unsigned long (32-bit) value. 


Implementation Specifics 
The _getlong subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the _getlong subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 

/etc/resolv.conf Lists name server and domain names. 

/usr/include/resolv.h Contains global information used by the resolver 
subroutines. 

/usr/include/arpa/nameser.h Defines Internet name server structures and 
constants. 

/usr/include/sys/types.h Contains definitions of unsigned data types. 

/usr/include/netinet/in.h Contains Internet constants and structures. 
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Related Information | | 
Domain name access subroutines are the res_init subroutine, res_mkquery subroutine, 
and res_send subroutine. 


Domain name translation subroutines are the dn_comp subroutine, dn_expand subroutine, 
dn_find subroutine,and dn_skipname subroutine. 


Byte stream and boundary retrieval subroutines are the _getshort subroutine, putshort 
subroutine, and putlong subroutine. 
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getnetbyaddr Subroutine 


Purpose 
Gets network entry by address. 

Library 
(libc.a) 

Syntax 
#include <netdb.h> 
struct netent *getnetbyaddr (Network, Type) 
long Network; 
int Type; 

Description 
The getnetbyaddr subroutine retrieves information from the /etc/networks file using the 
network address as a Search key. The getnetbyaddr subroutine searches the file 
sequentially from the start of the file until it encounters a matching net number and type or 
until it reaches the end of the file. 
The getnetbyaddr subroutine returns a pointer to a netent structure, which contains the 
equivalent fields for a network description line in the /etc/networks file. The netent 
structure is defined in the netdb.h header file. 
Use the endnetent subroutine to close the /etc/networks file. 

Parameters 
Network Specifies the number of the network to be located. 
Type Specifies the address family for the network. The only supported value is 

AF_INET. 


Return Values 
Upon successful completion, the getnetbyaddr returns a pointer to a netent structure. 


Note: The return value points to static data that is overwritten by subsequent calls. 
If an error occurs or the end of the file is reached, the getnetbyaddr subroutine returns a 
NULL pointer. 


Implementation Specifics 
The getnetbyaddr subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getnetbyaddr subroutine must be compiled with BSD 
defined. In addition, when applicable, all socket applications must include the BSD library 


libbsd. 

Files 
/etc/networks Contains official network names. 
/usr/include/netdb.h Contains the network database structures. 
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Related Information | 
Additional network information retrieval subroutines are the endnetent subroutine, 
getnetbyname subroutine, getnetent subroutine, and setnetent subroutine. 
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getnetbyname 


getnetbyname Subroutine 


Purpose 
Library 


Syntax 


Gets network entry by name. 


(libc.a) 


#include <netdb.h> 


struct netent *getnetbyname (Name) 
char *Name; 


Description 


Parameter 


The getnetbyname subroutine retrieves information from the /etc/networks file using the 
domain Name as a search key. The getnetbyname subroutine searches the /etc/networks 
file sequentially from the start of the file until it encounters a matching net name or until it 
reaches the end of the file. 


The getnetbyname subroutine returns a pointer to a netent structure, which contains the 
equivalent fields for a network description line in the /etc/networks file. The netent 
structure is defined in the netdb.h header file. 


Use the endnetent subroutine to close the /etc/networks file. 


Name Points to a string containing the name of the network. 


Return Values 


Upon successful completion, the getnetbyname subroutine returns a pointer to a netent 
structure. 


Note: The return value points to static data that is overwritten by subsequent calls. 


If an error occurs or the end of the file is reached, the getnetbyname subroutine returns a 
NULL pointer. 


Implementation Specifics 


Files 


The getnetbyname subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getnetbyname subroutine must be compiled with BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


/etc/networks Contains official network names. 
/usr/include/netdb.h Contains the network database structures. 
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Related Information 
Additional network information retrieval subroutines are the endnetent subroutine, 
getnetbyaddr subroutine, getnetent subroutine, and setnetent subroutine. 
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getnetent Subroutine 


Purpose 

Gets network entry. 
Library 

(libc.a) 
Syntax 

#include <netdb.h> 

struct netent *getnetent ( ) 
Description 


The getnetent subroutine retrieves network information by opening and sequentially reading 
the /etc/networks file. 


The getnetent subroutine returns a pointer to a netent structure, which contains the 
equivalent fields for a network description line in the /etc/networks file. The netent 
structure is defined in the netdb.h header file. 


Use the endnetent subroutine to close the /etc/networks file. 


Return Values 
Upon successful completion, the getnetent subroutine returns a pointer to a netent 
structure. 


Note: The return value points to static data that is overwritten by subsequent calls. 
If an error occurs or the end of the file is reached, the getnetent subroutine returns a NULL 
pointer. 


Implementation Specifics 
The getnetent subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getnetent subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/networks Contains official network names. 
/usr/include/netdb.h Contains the network database structures. 


Related Information 
Additional network information retrieval subroutines are the endnetent subroutine, 
getnetbyaddr subroutine, getnetbyname subroutine, and setnetent subroutine. 
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getpeername Subroutine 


Purpose 
Gets the name of the peer socket. 
Syntax 
#include<sys/types.h> 
#include <sys/socket.h> 
int getpeername (Socket, Name, NameLength); 
int Socket; 
struct sockaddr *Name; 
int *NameLength; 
Description 
The getpeername subroutine retrieves the Name of the peer socket connected to the 
specified socket. The Name parameter contains the address of the peer socket upon 
successful completion. 
A process created by another process can inherit open sockets. The created process may 
need to identify the addresses of the sockets it has inherited. The getpeername subroutine 
allows a process to retrieve the address of the peer socket at the remote end of the socket 
connection. 
Note: The getpeername subroutine operates only on connected sockets. 
A process can use the getsockname subroutine to retrieve the local address of a socket. 
Parameters 
Socket Specifies the descriptor number of a connected socket. 
Name Points to a sockaddr structure that contains the address of the 


destination socket upon successful completion. The /sys/socket.h 
file defines the sockaddr structure. 


NameLength Points to the size of the address structure. Initializes the 
NameLength to indicate the amount of space pointed to by the 
Name parameter. Upon successful completion, it returns the actual 
size of the Name parameter returned. 


Return Value 
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Upon successful completion, a value of 0 (zero) is returned and the Name parameter holds 
the address of the peer socket. 


lf the getpeername subroutine fails, the system handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable errno 
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Error Codes 
The getpeername subroutine fails if any one of the following errors occur: 


EBADF The Socket parameter is not valid. 
ENOTSOCK The Socket parameter refers to a file, not a socket. 


ENOTCONN The socket is not connected. 


ENOBUFS Insufficient resources were available in the system to complete the call. 
EFAULT The Address parameter is not in a writable part of the user address 
space. 
Examples 


1. The following program fragment illustrates the use of the getpeername subroutine to 
return the address of the peer connected on the other end of the socket. 


struct sockaddr _in name; 
int namelen = sizeof(name); 


if(getpeername(0,(struct sockaddr*)&name, &namelen)<0) { 
syslog(LOG ERR,“getpeername: %m”); 
exreti)> 

} else 
syslog(LOG_ INFO,”Connection from %s”,inet_ntoa(name.sin_ addr) ); 


Implementation Specifics 
The getpeername subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getpeername subroutine must be compiled with _BSD 
defined. In addition, when applicable, all socket applications must include the BSD library 


libbsd. 
Files 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 
buffer queues. 
/usr/include/sys/types.h Contains definitions of unsigned data types. 


Related Information 
The socket subroutines to create and name sockets are the accept subroutine, bind 
subroutine, and socket subroutine. 


The socket subroutine used to retrieve a local socket address is the getsockname 
subroutine. 
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getprotobyname Subroutine 


Purpose | 
Gets protocol entry from the /etc/protocols file by protocol name. 

Library 
(libe.a) 

Syntax 
#include <netdb.h> 
struct protoent *getprotobyname (Name) 
char *Name; 

Description 
The getprotobyname (get protocol by name) subroutine retrieves protocol information from 
the /etc/protocols file by protocol name. 
An application program can use the getprotobyname subroutine to access a protocol 
name, its aliases, and protocol number. 
The getprotobyname subroutine searches the protocols file sequentially from the start of 
the file until it finds a matching protocol name or until it reaches the end of the file. 
The subroutine returns a pointer to a protoent structure, which contains fields for a line of 
information in the protocols file. The netdb.h header file defines the protoent structure. 
Use the endprotoent subroutine to close the protocols file. 

Parameters 


Name Specifies the protocol name. 


Return Values 


Upon successful completion, the getprotobyname subroutine returns a pointer to a 
protoent structure. 


Note: The return value points to static data that is overwritten by subsequent calls. 


If an error occurs or the end of the file is reached, the getprotbyname subroutine returns a 
NULL pointer. 


unplementaton Specifics 


Files 
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The getprotobyname subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getprotobyname subroutine must be compiled with _BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


/etc/protocols Contains protocol information. 
/usr/include/netdb.h Contains the network database structures. 
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Related Information 
Additional protocol information retrieval subroutines are the endprotoent subroutine, 
getprotobynumber subroutine, getprotoent subroutine, and setprotoent subroutine. 
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getprotobynumber Subroutine 


Purpose 
Gets a protocol entry from the /etc/protocols file by number. 

Library 
(libc.a) 

Syntax 
#include <netdb.h> 
struct protoent *getprotobynumber (Protocol) 
int Protocol; 

Description 
The getprotobynumber (get protocol by number) subroutine retrieves protocol information 
from the /etc/protocols file using a specified protocol number as a search key. 
An application program can use the getprotobynumber subroutine to access a protocol 
name, its aliases, and protocol number. 
The getprotobynumber subroutine searches the /ete/protocols file sequentially from the 
start of the file until it finds a matching protocol name or protocol number, or until it reaches 
the end of the file. | 
The subroutine returns a pointer to a protoent structure, which contains fields for a line of 
information in the /etc/protocols file. The netdb.h file defines the protoent structure. 
Use the endprotoent subroutine to close the /etc/protocols file. 

Parameter 


Protocol Specifies the protocol number. 


Return Values 


Upon successful completion, the getprotobynumber subroutine, returns a pointer to a 
protoent structure. 


Note: The return value points to static data that is overwritten by subsequent calls. 


lf an error occurs or the end of the file is reached, the getprotobynumber subroutine 
returns a NULL pointer. 


Implementation Specifics 
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The getprotobynumber subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getprotobynumber subroutine must be compiled with _BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 
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Files 
/etc/protocols Contains protocol information. 


/usr/include/netdb.h Contains network database structures. 


Related Information 
Additional protocol information retrieval subroutines are the endprotoent subroutine, 
getprotobyname subroutine, getprotoent subroutine, and setprotoent subroutine. 
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getprotoent Subroutine 


Purpose 

Gets protocol entry from the /etc/protocols file. 
Library 

(libe.a) 
Syntax 

#include <netdb.h> 

struct protoent *getprotoent ( ) 
Description 


The getprotoent (get protocol entry) subroutine retrieves protocol information from the 
/etc/protocols file. 


An application program can use the getprotoent subroutine to access a protocol name, its 
aliases, and protocol number. 


The getprotoent subroutine opens and performs a sequential read of the /etc/protocols 
file. 


The getprotoent subroutine returns a pointer to a protoent structure, which contains the 
fields for a line of information in the /etc/protocols file. The netdb.h header file defines the 
protoent structure. 


Use the endprotoent subroutine to close the /etc/protocols file. 


Return Values 


Upon successful completion, the getprotoent subroutine returns a pointer to a protoent 
structure. 


Note: The return value points to static data that is overwritten by subsequent calls. 


If an error occurs or the end of the file is reached, the getprotoent subroutine returns a 
NULL pointer. 


Implementation Specifics 


Files 
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The getprotoent subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getprotoent subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


/etc/protocols Contains protocol information. 
/usr/include/netdb.h Contains the network database structures. 
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Related Information 
Additional protocol information retrieval subroutines are the endprotoent subroutine, 
getprotobyname subroutine, getprotobynumber subroutine, and setprotoent subroutine. 
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getservbyname Subroutine 


Purpose 


Library 


Syntax 


Gets service entry by name. 


(libce.a) 


#include <netdb.h> 


struct servent *getservbyname (Name, Protocol) 
char *Name, *Protocol; 


Description 


The getservbyname (get service by name) subroutine retrieves an entry from the 
/etc/services file using the service name as a search key. 


An application program can use the getservbyname subroutine to access a service, service 
aliases, the protocol for the service, and a protocol port number for the service. 


The getservbyname subroutine searches the /etc/services file sequentially from the start : 
the file until it finds one of the following: 


e amatching name and protocol number 
e amatching name when the Protoco/ parameter is set to 0 (zero) 
e the end of the file | 


Upon locating a matching name and protocol, the getservbyname returns a pointer to the 
servent structure, which contains fields for a line of information from the /etc/services file. 
The netdb.h header file defines the servent structure and structure fields. 


Use the endservent subroutine to close the /etc/host file. 


Parameters 


Name Specifies the name of a service. 


Protocol Specifies a protocol for use with the specified service. 


Return Value 
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The getservbyname subroutine returns a pointer to a servent structure when a successful 
match occurs. 


Note: The return value points to static data that is overwritten by subsequent calls. 


If an error occurs or the end of the file is reached, the getservbyname subroutine returns a 
NULL pointer. 
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Implementation Specifics 


Files 


The getservbyname subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getservbyname subroutine must be compiled with BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


/etc/services Contains service names. 
/usr/include/netdb.h Contains network database structures. 


Related Information 


Additional service information retrieval subroutines are the endservent subroutine, 
getservbyport subroutine, getservent subroutine, and setservent subroutine. 


Protocol information retrieval subroutines are the endprotoent subroutine, 


getprotobynumber subroutine, getprotobyname subroutine, getprotoent subroutine, and 
setprotoent subroutine. 
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getservbyport Subroutine 


Purpose 
Gets service entry by port. 

Library 
(libc.a) 

Syntax 
#include <netdb.h> 
struct servent *getservbyport (Port, Protocol) 
int Port; 
char *Protocol; 

Description 
The getservbyport (get service by port) subroutine retrieves an entry from the /etc/services 
file using a port number as a Search key. 
An application program can use the getservbyport subroutine to access a service, service 
aliases, the protocol for the service, and a protocol port number for the service. 
The getservbyport subroutine searches the services file sequentially from the beginning of 
the file until it finds one of the following: 
e amatching protocol and port number 
e amatching protocol when the Port parameter value equals 0 (zero) 
e the end of the file 
Upon locating a matching protocol and port number or upon locating a matching protocol 
only if the Port parameter value equals 0 (zero), the getservbyport subroutine returns a 
pointer to a servent structure, which contains fields for a line of information in the 
/etc/services file. The netdb.h header file defines the servent structure and structure 
fields. 
Use the endservent subroutine to close the /ete/services file. 

Parameters 
Port Specifies the port where a service resides. 
Protocol Specifies a protocol for use with the service. 


Return Value 
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Upon successful completion, the getservbyport subroutine returns a pointer to a servent 
structure. 


Note: The return value points to static data that is overwritten by subsequent calls. 


if an error occurs or the end of the file is reached, the getservbyport subroutine returns a 
NULL pointer. 
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Implementation Specifics 


Files 


The getservbyport subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getservbyport subroutine must be compiled with _BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


/etc/services Contains service names. 
/usr/include/netdb.h Contains network database structures. 


Related Information 


Additional service information retrieval subroutines are the endservent subroutine, 
getservbyname subroutine, getservent subroutine, and setservent subroutine. 


Protocol information retrieval subroutines are the endprotoent subroutine, 
getprotobynumber subroutine, getprotobyname subroutine, getprotoent subroutine, and 
setprotoent subroutine. 
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getservent Subroutine 


Purpose 

Gets services file entry. 
Library 

(libc.a) 
Syntax 

#include <netdb.h> 

struct servent “getservent ( ) 
Description 


The getservent (get service entry) subroutine opens and reads the next line of the 
/etc/services file. 


An application program can use the getservent subroutine to retrieve information about 
network services and the protocol ports they use. 


The getservent subroutine returns a pointer to a servent structure, which contains fields for 
a line of information from the /etc/services file. The servent structure is defined in the 
netdb.h header file. 


The /etc/services file remains open after a call by the getservent subroutine. To close the 
/etc/services file after each call, use the setservent subroutine. Otherwise, use the 
endservent subroutine to close the /ete/services file. 


Return Value 


The getservent subroutine returns a pointer to a servent structure when a successful match 
occurs. 


Note: The return value points to static data that is overwritten by subsequent calls. 
If an error occurs or the end of the file is reached, the getservent subroutine returns a 
NULL pointer. 


implementation Specifics 
The getservent subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getservent subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/services Contains service names. 
/usr/include/netdb.h | Contains network database structures. 


Related Information 


Additional service information retrieval subroutines are the endservent subroutine, 
getservbyname subroutine, getservbyport subroutine, and setservent subroutine. 
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Protocol information retrieval subroutines are the endprotoent subroutine, 
getprotobynumber subroutine, getprotobyname subroutine, getprotoent subroutine, and 
setprotoent subroutine. 
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_getshort Subroutine 


Purpose 
Retrieves short byte quantities. 

Library 
(libc.a) 

Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 
unsigned short getshort (VessagePtr 
u_char *MessagePtr 

Description | 
The _getshort subroutine gets quantities from the byte stream or arbitrary byte boundaries. 
The _getshort subroutine is one of a set of subroutines that form the resolver, a set of 
functions that resolve domain names. Global information that is used by the resolver 
subroutines is kept in the _res data structure. The /include/resolv.h file contains the _res 
structure definition. 

Parameters 


MessagePir Specifies a pointer into the byte stream. 


Return Value 
The _getshort subroutine returns an unsigned short (16-bit) value. 


Implementation Specifics 
The _getshort subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the _getshort subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 

/etc/resolv.conf Defines name server and domain names. 

/usr/include/resolv.h Contains global information used by the resolver 
subroutines. 

/usr/include/arpa/nameser.h Defines Internet name server structures, constants, 
and values. 

/usr/include/sys/types.h Defines unsigned data types. 

/usr/include/netinet/in.h Defines Internet constants and structures. 
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Related Information 
Domain name access subroutines are the res_init subroutine, res_mkquery subroutine, 
and res_send subroutine. 


Domain name translation subroutines are the dn_comp subroutine, dn_expand subroutine, 
dn_find subroutine, and dn_skipname subroutine. 


Byte stream and byte boundary retrieval subroutines are the _getlong subroutine, putshort 
subroutine, and putlong subroutine. 
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getsockname Subroutine 


Purpose 
Gets the socket name. 

Syntax 
#include<sys/types.h> 
#include <sys/socket.h> 
int getsockname(Socket, Name, NameLength) 
int Socket; 
struct sockaddr *Name; 
int *NameLength; 

Description 
The getsockname subroutine retrieves the locally bound address of the specified socket. 
The socket address represents a port number in the Internet domain and is stored in the 
sockaddr structure pointed to by the Name parameter. The /sys/socket.h file defines the 
sockaddr data structure. | 
Note: The getsockname subroutine does not perform operations on UNIX domain sockets. 
A process created by another process can inherit open sockets. To use the inherited socket, 
the created process needs to identify their addresses. The getsockname subroutine allows 
a process to retrieve the local address bound to the specified socket. 
A process can use the getpeername subroutine to determine the address of a destination 
socket in a socket connection. 

Parameters 
Socket Specifies the socket for which the local address is desired. 
Name Points to the structure containing the local address of the specified 

socket. 

NameLength Specifies the size of the local address in bytes. Initialize the value 


pointed to by the NameLength parameter to indicate the amount of 
space pointed to by the Name parameter. 


Return Value 
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Upon successful completion, a value of 0 (zero) is returned, and the NameLength parameter 
points to the size of the socket address. 


If the getsockname subroutine fails, the subroutine handler performs the following 
functions: 


e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable errno. 
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Error Codes 


Examples 


The getsockname subroutine fails if any one of the following errors occur: 
EBADF The Socket parameter is not valid. 


ENOTSOCK The Socket parameter refers to a file, not a socket. 


ENOBUFS Insufficient resources are available in the system to complete the call. 
EFAULT The Address parameter is not in a writable part of the user address 
space. 


1. The Reading Internet Domain Datagrams program fragment illustrates the use of the 
getsockname subroutine. 


2. The Check for Pending Connections program fragrment illustrates the use of the 
getsockname subroutine. 


Implementation Specifics 


Files 


The getsockname subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the getsockname subroutine must be compiled with BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


/usr/include/sys/socket.h Contains socket definitions. 


/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 
buffer queues. 


/usr/include/sys/types.h Contains definitions of unsigned data types. 


Related Information 


Socket subroutines to name and create sockets are the accept subroutine, the bind 
subroutine, and socket subroutine. 


The socket subroutine to get the destination address of a connected socket is the 
getpeername subroutine. 
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getsockopt Subroutine 


Purpose 
Gets options on sockets. 

Syntax 
#include <sys/types.h> 
#include <sys/socket.h> 
int getsockopt (Socket, Level, OptionName, OptionValue, OptionLength) 
int Socket, Level, OptionName; 
char *OptionValue; 
int *OptionLength; 

Description | 
The getsockopt subroutine allows an application program to query socket options. The 
calling program specifies the name of the socket, the name of the option, and a place to 
store the requested information. The operating system gets the socket option information 
from its internal data structures and passes the requested information back to the calling 
program. 
Options may exist at multiple protocol levels. They are always present at the uppermost 
socket level. When retrieving socket options, specify the level at which the option resides 
and the name of the option. . 

Parameters 
Socket Specifies the unique socket name. 
Level Specifies the protocol! level at which the option resides. To retrieve options 

at the: 

e Socket level—specify the Leve/ parameter as SOL_SOCKET. 

e Other levels—supply the appropriate protocol number for the protocol 
controlling the option. For example, to indicate that an option will be 
interpreted by the TCP protocol, set Leve/ to the protocol number of TCP, 
as defined in the netinet/in.h header file. 

OptionName 

Specifies a single option. The OptionName parameter and any specified 

options are passed uninterpreted to the appropriate protocol module for 

interpretation. The sys/socket.h header file contains definitions for socket 
level options. The socket level options can be enabled or disabled; they 
operate in a toggle fashion. The getsockopt subroutine retrieves 
information about the following options: 

e SO_DEBUG Specifies the recording of debugging 
information. This option enables or disables 
debugging in the underlying protocol! modules. 

e SO _ACCEPTCONN Socket had a listen call. 
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SO_REUSEADDR 


SO_KEEPALIVE 


SO_DONTROUTE 


SO_LINGER 


SO_OOBINLINE 


SO_SNDBUF 
SO_RCVBUF 
SO_SNDLOWAT 
SO_RCVLOWAT 
SO_SNDTIMEO 


getsockopt 


Specifies whether transmission of broadcast 
messages is supported. The option enables 
or disables broadcast support. 


Specifies that the rules used in validating 
addresses supplied by a bind subroutine 
should allow reuse of local addresses. This 
option enables or disables reuse of local 
addresses. 


Keeps connections active. Enables or diables 
the periodic transmission of messages on a 
connected socket. If the connected socket 
fails to respond to these messages, the 
connection is broken and processes using that 
socket are notified with a SIGPIPE signal. 


Does not apply routing on outgoing 
messages. Indicates outgoing messages 
should bypass the standard routing facilities. 
Directs messages to the appropriate network 
interface according to the network portion of 
the destination address. This option enables 
or disables routing of outgoing messages. 


Lingers on a close subroutine if data is 
present. This option controls the action taken 
when unsent messages queue on a socket 
and a close subroutine is performed. It uses 
a struct Linger parameter defined in the 
sys/socket.h file. The parameter specifies 
the state of the option and linger interval. 
Specify the linger interval by using the 
setsockopt subroutine when requesting 
SO_LINGER. This option enables or disable 
lingers on a close subroutine. 


lf SO_LINGER is set, the system blocks the 
process during the close subroutine uniil it 
can transmit the data or until the time expires. 
If SO_LINGER is not specified, and a close 
subroutine is issued, the system handles the 
call in a way that allows the process to 
continue as quickly as possible. 


Leaves received out—of—band data (data 
marked urgent) in line. This option enables or 
disables the receipt of out-of-band data. 


Retrieves buffer size information. 
Retrieves buffer size information. 
Retrieves low-water mark information. 
Retrieves low-water mark information. 


Retrieves time—out information. 
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Option Value 


SO_RCVTIMEO Retrieves time—out information. 

SO_ERROR Retrieves information about error status and 
clear 

SO_TYPE Retrieves information about a socket type. 


Specifies a pointer to the address of a buffer. The OptionValue parameter 
takes an integer parameter. The OptionValue parameter should be set toa 
nonzero value to enable a Boolean option or to a value of 0 (zero) to disable 
the option. The following options enable and disable in the same manner: 


SO_DEBUG 
SO_REUSEADDR 
SO_KEEPALIVE 
SO_DONTROUTE 
SO_BROADCAST 
SO_OOBINLINE 


OptionLength Specifies the length of the OptionValue. The OptionLength parameter 
initially contains the size of the buffer pointed to by the Option Value 
parameter. On return, the OptionLength parameter is modified to indicate 
the actual size of the value returned. If no option value is supplied or 
returned, the OptionValue parameter can be 0 (zero). 


Options at other protocol levels vary in format and name. 


Return Value 
Upon successful completion, the getsockopt subroutine returns a value of 0 (zero). 


If the getsockopt subroutine fails, the subroutine handler performs the following actions: 


e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable errno 


Error Codes 
The getsockopt subroutine fails if any one of the following errors occur: 
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EBADF 
ENOTSOCK 
ENOPROTOOPT 
EFAULT 


The Socket parameter is not valid. 
The Socket parameter refers to a file, not a socket. 
The option is unknown. 


The address pointed to by the Option Value parameter is not ina 
valid (writable) part of the process space, or the OptionLength 
parameter is not in a valid part of the process address space. 
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Example 
1. The following program fragment illustrates the use of the getsockopt subroutine to 
determine an existing socket type. 


#include <sys/types.h> 

#include <sys/socket.h> 

int type, size; 

size = sizeof(int); 

if(getsockopt(s, SOL SOCKET, SO_TYPE, (char*)&type, &size)<0) { 


} 
Implementation Specifics 
The getsockopt subroutine is part of AIX Base Operating System (BOS) Runtime. 
All applications containing the getsockopt subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/sys/socket.h Contains socket definitions. 


/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 
buffer queues. 


/usr/include/sys/types.h Contains definitions of unsigned data types. 
Related Information 
Socket subroutines to manipulate protocol information are the endprotoent subroutine, 


getprotobynumber subroutine, getprotoent subroutine, setprotoent subroutine, and 
socket subroutine. 


The socket subroutine to set socket options is the setsockopt subroutine. 


Socket subroutines to assign names to sockets and end communications, respectively, are 
the bind subroutine and close subroutine. 
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hton! Subroutine 


Purpose 
Converts an unsigned long integer from host byte order to Internet network byte order. 


Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 


unsigned long htonl (HostLong) 
~ unsigned long HostLong; 


Description 
The htonl (host to network long) subroutine converts an unsigned long (32-bit) integer from 
host byte order to Internet network byte order. 


The Internet network requires addresses and ports in network standard byte order. Use the 
htonl subroutine to convert the host integer representation of addresses and ports to 
Internet network byte order. 


The htonl subroutine is defined in the netinet/in.h file as a macro. 


Parameter 
HostLong Specifies a 32-bit integer in host byte order. 


Return Values 
The htonl subroutine returns a 32-bit integer in Internet network byte order (most significant 
byte first). 


Implementation Specifics 
The htonl subroutine is part of AIX Base Operating System (BOS) Runtime. 
All applications containing the htonl subroutine must be compiled with _BSD defined. In 


addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/sys/types.h Defines unsigned data types. 
/usr/include/netinet/in.h Defines Internet constants and structures. 


Related Information 
Additional conversion subroutines are the htons subroutine, ntohl subroutine, and ntohs 
subroutine. 
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htons Subroutine 


Purpose 
Converts an unsigned short integer from host byte order to Internet network byte order. 
Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
unsigned short htons (HostShort) 
unsigned short HostShort; 
Description 
The htons (host to network short) subroutine converts an unsigned short (16—bit) integer 
from host byte order to Internet network byte order. 
The Internet network requires ports and addresses in network standard byte order. Use the 
htons subroutine to convert addresses and ports from their host integer representation to 
network standard byte order. 
The htons subroutine is defined in the netinet/in.h file as a macro. 
Parameter 


HostShort Specifies a 16—bit integer in host byte order that is a host address or port. 


Return Values 


The htons subroutine returns a 16-bit integer in Internet network byte order (most 
significant byte first). 


All applications containing the htons subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


implementation Specifics 
The htons subroutine is part of AIX Base Operating System (BOS) Runtime. 


Files 
/usr/include/sys/types.h Contains definitions of unsigned data types. 
/usr/include/netinet/in.h Defines Internet constants and structures. 


Related Information 
Additional conversion subroutines are the hton! subroutine, ntoh! subroutine, and ntohs 
subroutine. 
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inet_addr Subroutine 


Purpose 
Converts Internet addresses to Internet numbers. 


Library 
(libe.a) 


Syntax 
#include <sys/socket.h> 
#include <sys/socketvar.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


unsigned long inet_addr (CharString) 
char *CharString; 


Description 
The inet_addr subroutine interprets character strings representing numbers expressed in 
the Internet . (dot) notation, returning numbers suitable for use as Internet addresses. 


All Internet addresses are returned in network order, with the first byte being the high-order 
byte. 


Use C language integers when specifying each part of a dot notation. 


Parameter 
CharString Represents a string of characters in the Internet address form. 


Return Values 


Upon successful completion, the inet_addr subroutine returns Internet addresses and 
Internet network numbers. 


If the inet_addr subroutine fails, the subroutine returns a value of —1 (negative one). 
Implementation Specifics 
The inet_addr subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the inet_addr subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/hosts Contains host names. 
/etc/networks Contains network names. 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 


buffer queues. 
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/usr/include/netinet/in.h Defines Internet constants and structures. 
/usr/include/darpa/inet.h Contains external definitions for functions in inet. 


Related Information 
Internet address conversion subroutines are the inet_Inaof subroutine, inet_makeaddr 
subroutine, inet_netof subroutine, inet_network subroutine, and inet_ntoa subroutine. 


Host information retrieval subroutines are the endhostent subroutine, gethostbyaddr 
subroutine, gethostbyname subroutine, sethostent subroutine. 


Network information retrieval subroutines are the endnetent subroutine, getnetbyaddr 
subroutine, getnetbyname subroutine, getnetent subroutine, and setnetent subroutine. 
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inet_Inaof Subroutine 


Purpose 
Separates local Internet addresses into their network number and local network address. 


Library 
(libc.a) 


Syntax 
#include<sys/socket.h> 
#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


int inet_Inaof (/nternetAddn 
struct in_addr /nternetAdar,; 


Description 
The inet_Inaof subroutine breaks apart Internet addresses, returning the local network 
address part. 


All Internet addresses are returned in network order, with the first byte being the high—order 
byte. All network numbers and local addresses are returned as integer values in machine 
format. Internet addresses are specified using a dot notation. 


Use C language integers when specifying each part of a dot notation. 


Parameter 
InternetAddr Specifies the Internet address to separate. 


Return Values 
Upon successful completion, the inet_network subroutine returns an Internet network 
number. 


If the inet_network subroutine fails, the subroutine returns a —1 (negative one). 
Implementation Specifics 
The inet_Inaof subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the inet_Inaof subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/hosts Contains host names. 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 


buffer queues. 
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/usr/include/netinet/in.h Defines Internet constants and structures. 
/usr/include/arpa/in.h Contains external definitions for functions in inet. 


Related Information 


The inet_addr subroutine, inet_makeaddr subroutine, inet_netof subroutine, 
inet_network subroutine, and inet_ntoa subroutine. 


Host information retrieval subroutines are the endhostent subroutine, gethostbyaddr 
subroutine, gethostbyname subroutine, and sethostent subroutine. 


Network information retrieval subroutines are the endnetent subroutine, getnetbyaddr 
subroutine, getnetbyname subroutine, getnetent subroutine, and setnetent subroutine. 
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inet_makeaddr Subroutine 


Purpose | 
Makes an Internet address. 
Library 
(libc.a) 
Syntax 
#include<sys/socket.h> 
#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 
struct in_addr inet_makeaddr (Nei, Loca/NetAddn 
int Net, Loca/NetAdar, 
Description 
The inet_makeaddr takes an Internet network number and a local network address and 
constructs an Internet address from it. 
All Internet addresses are returned in network order, with the first byte being the high—order 
byte. All network numbers and local addresses are returned as integer values in machine 
format. Internet addresses are specified using a dot notation. 
Use C language integers when specifying each part of a dot notation. 
Parameters 
Net Contains an Internet network number. 
LocalNetAddr Contains a local network address. 


Return Values 
Upon successful completion, the inet_addr subroutine returns an Internet address. 


If the inet_addr subroutine is unsuccessful, the subroutine returns a —1 (negative one). 
Implementation Specifics 
The inet_makeaddr subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the inet_makeaddr subroutine must be compiled with _BSD 
defined. In addition, when applicable, all socket applications must include the BSD library 


libbsd. 
Files 
/etc/hosts Contains host names. 
/usr/include/netinet/in.h Contains Internet constants and structures. 
/ust/include/arpa/inet.h Contains external definitions for functions in inet. 
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/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 
buffer queues. 
/usr/include/sys/socket.h Contains socket definitions. 


Related Information 
Internet address conversion subroutines are the inet_addr subroutine, inet_Inaof 
subroutine, inet_netof subroutine, inet_network subroutine, and inet_ntoa subroutine. 


Host information retrieval subroutines are the endhostent subroutine, gethostbyaddr 
subroutine, gethostbyname subroutine, sethostent subroutine. 


Network information retrieval subroutines are the endnetent subroutine, getnetbyaddr 
subroutine, getnetbyname subroutine, getnetent subroutine, and setnetent subroutine. 
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inet_netof Subroutine 


Purpose 
Separates network Internet addresses into their network number and local network address. 


Library 
(libe.a) 


Syntax 
#include <sys/socket.h> 
#include <sys/socketvar.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


int inet_netof (/nternetAdadr) 
struct in_addr /nternetAddr 


Description 


The inet_netof subroutine breaks apart Internet addresses, returning the network number. 
Internet addresses are specified using a dot notation. 


All Internet addresses are returned in network order, with the first byte being the high—order 
byte. 


Use C language integers when specifying each part of a dot notation. 


Parameter 
InternetAddr Specifies the Internet address to separate. 


Return Values 
Upon successful completion, the inet_netof subroutine returns a network number. 
If the inet_netof subroutine fails, the subroutine returns a —1 (negative one). 
Implementation Specifics 
The inet_netof subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the inet_netof subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/hosts Contains host names. 
/etc/networks Contains network names. 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 

buffer queues. 

/usr/include/netinet/in.h Defines Internet constants and structures. 
/usr/include/arpa/inet.h Contains external definitions for functions in inet. 
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Related Information 
Internet address conversion subroutines are the inet_addr subroutine, inet_Inaof 
subroutine, inet_makeaddr subroutine, inet_network subroutine, and inet_ntoa 
subroutine. 


Host information retrieval subroutines are the endhostent subroutine, gethostbyaddr 
subroutine, gethostbyname subroutine, and sethostent subroutine. 


Network information retrieval subroutines are the endnetent subroutine, getnetbyaddr 
subroutine, getnetbyname subroutine, getnetent subroutine, and setnetent subroutine. 
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inet_network Subroutine 


Purpose 
Converts Internet network addresses in . (dot) notation to Internet numbers. 


Library 
(libe.a) 


Syntax 
#include <sys/socket.h> 
#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


unsigned long inet_network (CharString) 
char *CharString; 


Description 
The inet_network subroutine interprets character strings representing numbers expressed 


in the Internet . (dot) notation and returns numbers suitable for use as Internet addresses 
and Internet network numbers. 


All Internet addresses are returned in network order, with the first byte being the high-order 
byte. 


Use C language integers when specifying each part of a dot notation. 


Parameter 
CharString Represents a string of characters in the Internet address form. 


Return Values 


Upon successful completion, the inet_network subroutine returns numbers suitable for use 
as Internet network numbers. 


If the inet_network subroutine fails, the subroutine returns a value of —1 (negative one). 
implementation Specifics 
The inet_network subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the inet_network subroutine must be compiled with _BSD 
defined. In addition, when applicable, all socket applications must include the BSD library 


libbsd. 

Files 
/etc/hosts Contains host names. 
/etc/networks Contains network names. 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and 


contains buffer queues. 
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/usr/include/netinet/in.h Defines Internet constants and structures. 
/usr/include/arpa/inet.h Contains external definitions for functions in 
Internet. 


Related Information 
Internet address conversion subroutines are the inet_addr subroutine, inet_Inaof 
subroutine, inet_makeaddr subroutine, inet_netof subroutine, and inet_ntoa subroutine. 


Host information retrieval subroutines are the endhostent subroutine, gethostbyaddr 
subroutine, gethostbyname subroutine, sethostent subroutine. 


Network information retrieval subroutines are the endnetent subroutine, getnetbyaddr 
subroutine, getnetbyname subroutine, getnetent subroutine, and setnetent subroutine. 
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inet_ntoa Subroutine 


Purpose 
Converts an Internet address into an ASCII string. 


Library 
(libe.a) 


Syntax 
#include <sys/socket.h> 
#include <netinet/in.h> 
#include <arpa/inet.h> 


char *inet_ntoa (/nternetAddr 
struct in_addr /nternetAdar, 


Description 
The inet_ntoa subroutine takes an Internet address and returns an ASCII string 
representing the Internet address in dot notation. All Internet addresses are returned in 
network order, with the first byte being the high-order byte. 


Use C language integers when specifying each part of a dot notation. 


Parameter 
InternetAddr Contains the Internet address to be converted to ASCIl. 


Return Values 
Upon successful completion, the inet_ntoa subroutine returns an Internet address. 
If the inet_ntoa subroutine fails, the subroutine returns a —1 (negative one). 
Implementation Specifics 
The inet_ntoa subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the inet_ntoa subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/hosts Contains host names. 
/etc/networks _ Contains network names. 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and 
contains buffer queues. 
/usr/include/netinet/in.h Defines Internet constants and structures. 
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Related Information 
Internet address conversion subroutines are the inet_addr subroutine, inet_Inaof 
subroutine, inet_makeaddr subroutine, inet_network subroutine, and inet_ntoa 
subroutine. 


Host information retrieval subroutines are the endhostent subroutine, gethostbyaddr 
subroutine, gethostbyname subroutine, and sethostent subroutine. 


Network information retrieval subroutines are the endnetent subroutine, getnetbyaddr 
subroutine, getnetbyname subroutine, getnetent subroutine, and setnetent subroutine. 
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listen Subroutine 


Purpose 
Listens for socket connections and limits the backlog of incoming connections. 


Syntax 
int listen (Socket, Backlog) 
int Socket, Backlog; 


Description 
The listen subroutine performs the following activities: 
1. Identifies the socket that receives the connections. 
2. Marks the socket as accepting connections. 
3. Limits the number (Backlog) of outstanding connection requests in the system queue. 


The maximum queue length (Backlog) that the listen subroutine can specify is ten (10). The 
maximum queue length is indicated by the SOMAXCONN value in the 
/include/sys/socket.h file. 


Parameters 
Socket Specifies the unique name for the socket. 


Backlog Specifies the maximum number of outstanding connection requests. 
Return Value 

Upon successful completion, the listen subroutine returns a value 0 (zero). 

If the listen subroutine fails, the subroutine handler performs the following functions: 

e Returns a value of —1 (negative one) to the calling program 

e Moves an error code, indicating the specific error, into the global variable errno. 


Error Codes 
The subroutine fails if any one of the following errors occurs: 


EBADF The Socket parameter is not valid. 

ECONNREFUSED A connection request arrived exceeding the backlog 
amount. 

ENOTSOCK The Socket parameter refers to a file, not a socket. 

EOPNOTSUPP The referenced socket is not a type that supports the listen 
subroutine. 
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Examples 
1. The following program fragment illustrates the use of the listen subroutine with five (5) 
as the maximum number of outstanding connections which may be queued awaiting 
acceptance by the server process. 


listen(s,5) 
Implementation Specifics 
The listen subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the listen subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and 
contains buffer queues. 
/usr/include/sys/types.h Contains definitions for unsigned data types. 


Related Information 


Other creation and connection socket subroutines are the accept subroutine, connect 
subroutine, and socket subroutine. 
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ntohi Subroutine 


Purpose 
Converts an unsigned long integer from Internet network standard byte order to host byte 
order. 
Syntax 
#include<sys/types.h> 
#include <netinet/in.h> 
unsigned long ntohl (NetLong) 
unsigned long NetLong; 
Description 
The ntohl (network to host long) subroutine converts an unsigned long (32-bit) integer from 
Internet network standard byte order to host byte order. 
Receiving hosts require addresses and ports in host byte order. Use the ntohl subroutine to 
convert Internet addresses and ports to the host integer representation. 
The ntohl subroutine is defined in the netinet/in.h file as a macro. 
Parameter 


NetLong Requires a 32-bit integer in network byte order. 


Return Values 
The ntohl subroutine returns a 32-bit integer in host byte order. 


Implementation Specifics 
The ntohl subroutine is part of AIX Base Operating System (BOS) Runtime. 
All applications containing the ntohl subroutine must be compiled with _BSD defined. In 


addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/sys/types.h Contains definitions of unsigned data types. 
/usr/include/netinet/in.h Defines Internet constants and structures. 


Related Information 


Additional conversion subroutines are the htonl subroutine, htons subroutine, and ntohs 
subroutine. 


Host address retrieval subroutines are the endhostent subroutine, gethostbyaddr 
subroutine, gethostbyname subroutine, and sethostent subroutine. 


Port retrieval subroutines are the endservent subroutine, the getservbyname subroutine, 
getservbyport subroutine, getservent subroutine, and setservent subroutine. 
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ntohs Subroutine 


Purpose 
Converts an unsigned short integer from Internet network byte order to host byte order. 


Syntax 
#include<sys/types.h> 
#include <netinet/in.h> 


unsigned short ntohs (NetShorf) 
unsigned short NefShort; 


Description 
The ntohs (network to host short) subroutine converts an unsigned short (16-bit) integer 
from Internet network byte order to the host byte order. 


Receiving hosts require Internet addresses and ports in host byte order. Use the ntohs 
subroutine to convert Internet addresses and ports to the host integer representation. 


The ntohs subroutine is defined in the netinet/in.h file as a macro. 


Parameter 
NetShort Requires a 16-bit integer in network standard byte order. 


Return Value 
The ntohs subroutine returns the supplied integer in host byte order. 


implementation Specifics 
The ntohs subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the ntohs subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/sys/types.h Contains definitions of unsigned data types. 
/usr/include/netinet/in.h Defines Internet constants and structures. 


Related Information 
Additional conversion subroutines are the htonl subroutine, htons subroutine, and ntohl 
subroutine. 


Host address retrieval subroutines are the endhostent subroutine, gethostbyaddr 
subroutine, gethostbyname subroutine,and sethostent subroutine. 


Port retrieval subroutines are the endservent subroutine, getservbyname subroutine, 
getservbyport subroutine, getservent subroutine, and setservent subroutine. 
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_putlong Subroutine 
Purpose 
Places long byte quantities into the byte stream. 
Library 
(libe.a) 
Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 
void _putlong (Long, MessagePtr 
unsigned long Long; 
u_char *MessagePtr, 
Description 
The _putlong subroutine places long byte quantities into the byte stream or arbitrary byte 
boundaries. 
The _putlong subroutine is one of a set of subroutines that form the resolver, a set of 
functions that resolve domain names. Global information that is used by the resolver 
subroutines is kept in the _res data structure. The /include/resolv.h file contains the _res 
structure definition. 
Parameters 


Long Represents a 32-bit integer. 


MessagePtr Represents a pointer into the byte stream. 


Implementation Specifics 


Files 
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The _putlong subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the _putlong subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


/etc/resolv.conf Lists the name server and domain name. 

/usr/include/resolv.h Contains global information used by the resolver 
subroutines. 

/usr/include/arpa/nameser.h Defines the Internet name server structure. 

/usr/include/sys/types.h Contains definitions of unsigned data types. 

/usr/include/netinet/in.h Defines Internet constants and structures. 
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Related Information 


Domain name access subroutines are the res_init subroutine, res_mkquery subroutine, 
and res_send subroutine. 


Domain name translation subroutines are the dn_comp subroutine, dn_expand subroutine, 
dn_find subroutine, and dn_skipname subroutine. 


Byte stream and byte boundary retrieval subroutines are the _getlong subroutine, 
_getshort subroutine, and putshort subroutine. 
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Places short byte quantities into the byte stream. 


(libc.a) 


#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


void _putshort (Short, MessagePtn 
unsigned short Short, 
u_char *MessagePtr, 


Description 


The _putshort subroutine puts short byte quantities into the byte stream or arbitrary byte 
boundaries. 


The _putshort subroutine is one of a set of subroutines that form the resolver, a set of 
functions that resolve domain names. Global information that is used by the resolver 
subroutines is kept in the _res data structure. The /include/resolv.h file contains the _res 
structure definition. 


Parameters 


Short Represents a 16-bit integer. 


MessagePtr Represents a pointer into the byte stream. 


Implementation Specifics 


Files 
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The __putshort subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the __ putshort subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


/etc/resolv.conf Lists the name server and domain name. 


/usr/include/resolv.h Contains global information used by the resolver 
subroutines. 

/usr/include/arpa/nameser.h Contains the Internet name server. 

/usr/include/sys/types.h Defines unsigned data types. 

/usr/include/netinet/in.h Contains Internet constants and structures. 
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Related Information 
Domain name access subroutines are the res_init subroutine, res_mkquery subroutine, 
and res_send subroutine. 


Domain name translation subroutines are the dn_comp subroutine, dn_expand subroutine, 
dn_find subroutine, and dn_skipname subroutine. 


Byte stream and byte boundary retrieval subroutines are the _getlong subroutine, 
_getshort subroutine, and putlong subroutine. 
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Purpose 


Library 


Syntax 


- -f. 


ubroutine 


Allows execution of commands on a remote host 


(libc.a) 


int remd (Host, Port, LocalUser, RemoteUser, Command, ErrFileDesc) 
char **Host; 

u_short Port; 

char *Loca/User, * RemoteUser, *Command; 

int *ErrFileDesc; 


Description 


The remd (remote command) subroutine allows execution of certain commands on a remote 
host that supports rshd, rlogin, and rpc among others. 


Only processes with an effective user ID of root user can use the remd subroutine. An 
authentication scheme based on remote port numbers is used to verify permissions. Ports 
in the range from 0 to 1023 can only be used by a root user. 


The remd subroutine looks up a host via the nameserver or if the local nameserver isn’t 
rurining, via the /etc/hosts file. 


If the connection succeeds, a socket in the Internet domain of type SOCK_STREAM is 
returned to the calling process and given to the remote command as standard input (stdin) 
and standard output (stdout). 


Always specify the Hostname. If the local domain and remote domain are the same, 
specifying the domain parts is optional. 


Parameters 
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Host Specifies the name of a remote host that is listed in the /etc/hosts file. If 


the specified name of the host is not found in this file, the remd subroutine 
fails. 


Port Specifies the well-known port to use for the connection. The /etc/services 
file contains the DARPA Internet services, their ports, and socket types. 


LocalUser and RemoteUser 
Points to user names that are valid at the local and remote host, 
respectively. Any valid user name can be given. 


Command Specifies the name of the command to be executed at the remote host. 


ErrFileDesc Specifies an integer controlling the set up of communications channels. 
Integer options are as follows: 


e Not 0 (zero) = an auxiliary channel to a control process is set up, and the 
ErrFileDesc parameter points to the file descriptor for the channel. The 
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control process provides diagnostic output from the remote command on 
this channel and also accepts bytes as signal numbers to be forwarded to 
the process group of the command. 


e 0 (zero) = the standard error (stderr) of the remote command is the same 
as standard output (stdout), and no provision is made for sending 
arbitrary signals to the remote process. However, it is possible to send 
out—of—band data to the remote command. 


Return Values 
Upon successful completion, the remd subroutine returns a valid socket descriptor. 


Upon unsuccessful completion, the remd subroutine returns a value of —1 (negative one). 
The subroutine returns a —1 (negative one), if the effective user ID of the calling process is 
not root user or if the subroutine fails to resolve the host. 


Implementation Specifics 
The remd subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the remd subroutine must be compiled with BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/services Contains the service names, ports, and socket type. 
/etc/hosts . Contains host names and their addresses for hosts ina 
network. 
/etc/resolv.config Contains the name server and domain name. 


Related Information 
Additional remote command execution subroutines are the rresvport subroutine and 
ruserok subroutine. 


TCP/IP Interface Program commands are the rlogind command and rshd command. 
TCP/IP daemons are the named daemon. 


System calls to get and set the host name are, respectively, the gethostname subroutine 
and sethostname subroutine. 
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Purpose 
Receives messages from connected sockets. 
Syntax | 

#include <sys/types.h> 

#include <sys/socket.h> 

#include <sys/socketvar.h> 

int recv (Socket, Buffer, Length, Flags) 

int Socket, 

char *Buffer; 

int Length, Flags; 

Description 

The recv (receive) subroutine receives messages from a connected socket. The recvfrom 

and recvmsg subroutines receive messages from both connected and unconnected 

sockets. However, they are usually used for unconnected sockets only. 

The recv subroutine returns the length of the message. If a message is too long to fit in the 

supplied buffer, excess bytes may be truncated depending on the type of socket that issued 

the message. 

If ro messages are available at the socket, the recv subroutine waits for a message to 

arrive, unless the socket is nonblocking. If a socket is nonblocking, the system returns an 

error. 

Use the select subroutine to determine when more data arrives. 

Parameters 

Socket Specifies the socket descriptor. 

Buffer Specifies an address where the message should be placed. 

Length Specifies the size of the Buffer parameter. 

Flags Points to a value controlling the message reception. The ys/socket.h file 
defines the Flags value. The argument to receive a call is formed by 
logically ORing one or more of the following values: 

MSG_PEEK Peeks at incoming message. The data is treated as 
unread and the next recv (or similar call) will still return 
this data. 

MSG_OOB Processes out—of—band data. 
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Return Value 


Upon successful completion, the recv subroutine returns the length of the message in bytes. 
If the recv subroutine fails, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable errno 


Error Codes 


Implementation Specifics 


Files 


The recv subroutine fails if any one of the following errors occurs: 


EBADF The Socket parameter is not valid. 

ENOTSOCK The Socket parameter refers to a file, not a socket. 

EWOULDBLOCK The socket is marked nonblocking, and no connections are present 
to be accepted. 

EINTR A signal interrupted the recv subroutine before any data was 
available. 

EFAULT The data was directed to be received into a non-existent or 


protected part of the process address space. The Buffer is invalid. 
The recv subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the recv subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 
buffer queues. 

/usr/include/sys/types.h Contains definitions for unsigned data types. 


Related Information 


The fgets subroutine and fputs subroutine. 
Additional receive subroutines are the recvfrom subroutine and recvmsg subroutine. 


Subroutines for sending messages over sockets are the send subroutine, sendmsg 
subroutine, and sendto subroutine. 


Socket subroutines for disabling communications, creating sockets and monitoring data 


reception are, respectively, the select subroutine, shutdown subroutine, and socket 
subroutine. 


The read subroutine and write subroutine. 
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Purpose 


Syntax 


Receives messages from sockets. 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <sys/socket.h> 


int recvfrom (Socket, Buffer, Length, Flags, From, FromLength) 
int Socket; 

char * Buffer, 

int Length, Flags; 

struct sockaddr *From; 

int *FromLength; 


Description 


_ The recvfrom subroutine allows an application program to receives messages from 


unconnected sockets. The recvfrom subroutine is normally applied to unconnected sockets 


as it includes parameters that allow the calling program to specify the source point of the 
data to be received. 


To return the source address of the message, specify a non—Null value for the From 
parameter. The recvfrom subroutine initializes the FromLength parameter to the size of the 
buffer associated with the From parameter. On return, the recvfrom subroutine modifies the 
FromLength parameter to indicate the actual size of the stored address. The recvfrom 
subroutine returns the length of the message. If a message is too long to fit in the supplied 


buffer, excess bytes may be truncated depending on the type of socket that issued the 
message. 


If no messages are available at the socket, the recvfrom subroutine waits for a message to 


arrive, unless the socket is nonblocking. If the socket is nonblocking, the system returns an 
error. 


Parameters 
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Socket Specifies the socket descriptor. 
Buffer Specifies an address where the message should be placed. 
Length Specifies the size of the Buffer parameter. 


Flags Points to a value controlling the message reception. The argument to 


receive a Call is formed by logically ORing one or more of the values shown 
in the following list: 


MSG_PEEK Peeks at incoming message. 
MSG_OOB Processes out—of—band data. 
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From Points to a socket structure, filled in with source’s address. 
FromLength Specifies the length of the sender’s or source’s address. 


Return Value 


If the recvfrom subroutine is successful, the subroutine returns the length of the message in 
bytes. 


If the call is unsuccessful, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 
e Moves an error code, indicating the specific error, into the global variable errno 


Error Codes 
The recvfrom subroutine fails if any one of the following errors occurs: 


EBADF The Socket parameter is not valid. 

ENOTSOCK The Socket parameter refers to a file, not a socket. 

EWOULDBLOCK The socket is marked nonblocking, and no connections are 
present to be accepted. 

EFAULT The data was directed to be received into a non-existent or 
protected part of the process address space. The buffer is 
invalid. 


Implementation Specifics 
The recvfrom subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the recvfrom subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/ustr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 
buffer queues. 
/usr/include/sys/types.h Contains definitions for unsigned data types. 


Related Information 
The fgets subroutine and fputs subroutine. 


Additional socket receive subroutines are the recv subroutine and recvmsg subroutine. 


Subroutines for sending messages over sockets are the send subroutine, sendmsg 
subroutine, and sendto subroutine. 


Socket subroutines for disabling communications, creating sockets and monitoring data 


reception are, respectively, the select subroutine, shutdown subroutine, and socket 
subroutine. 
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The read subroutine and write subroutine. 
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recvmsg Subroutine 


Purpose 


Receives a message from any socket. 


Syntax 


#include <sys/types.h> 
#include <sys/socket.h> 


#include <sys/socketvar.h> 


int recvmsg (Socket, Message, Flags) 


int Socket; 


struct msghdr Message| ]; 


int Flags; 


Description 


The recvmsg subroutine receives messages from unconnected or connected sockets. The 
recvmsg subroutine returns the length of the message. If a message is too Jong to fit in the 
supplied buffer, excess bytes may be truncated depending on the type of socket that issued 


the message. 


lf no messages are available at the socket, the recvmsg subroutine waits for a message to 
arrive. If the socket is nonblocking and no messages are available, the recvmsg subroutine 


fails. 


Use the select subroutine to determine when more data arrives. 


The recvmsg subroutine uses a msghdr structure to decrease the number of directly 
supplied parameters. The msghdr structure is defined in the sys/socket.h header file. 


Parameters 
Socket 


Message 


Flags 


Specifies the unique name of the socket. 


Points to the address of the msghdr structure which contains both the 
address for the incoming message and the space for the sender address. 


Permits the subroutineer to exercise control over the reception of 
messages. The Flags parameter to receive a call is formed by logically 
ORing one or more of the values shown in the following list: 


MSG_PEEK Peeks at incoming message. 
MSG_OOB Processes out—of—band data. 


The /sys/socket.h file contains the possible values for the Flags parameter. 


Sockets 8—89 


recvmsg 


Return Value 
Upon successful completion, the length of the message in bytes is returned. 


If the recvmsg subroutine fails, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 
e Moves an error code, indicating the specific error, into the global variable errno 


Error Codes 
The recvmsg subroutine fails if any one of the following error codes occurs: 


EBADF The Socket parameter is not valid. 

ENOTSOCK The Socket parameter refers to a file, not a socket. 

EWOULDBLOCK The socket is marked nonblocking, and no connections are present 
to be accepted. 

EINTR The recvmsg subroutine was interrupted by delivery of a signal 
before any data was available for the receive. 

EFAULT The Address parameter is not in a writable part of the user address 
space. 


implementation Specifics 
The recvmsg subroutine is part of AIX Base Operating System (BOS) Runtime. 


Ail applications containing the recvmsg subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/socketvar.h Defines the kernel structure per socket and contains 
buffer queues. 
/usr/include/sys/types.h Contains definitions for unsigned data types. 


Related Information 
Additional socket receive subroutines are the recv subroutine and recvfrom subroutine. 


Socket send subroutines are the send subroutine, sendmsg subroutine, and sendto 
subroutine. 


Socket subroutines for closing communications, monitoring data broadcasts, and creating 


sockets are, respectively, the select subroutine, shutdown subroutine, and socket 
subroutine. 
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res_init Subroutine 


Purpose 
Searches for a default domain name and Internet address. 
Library 
(libe.a) 
Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 
void res_init ( ) 
Description 


The res_init subroutine reads the /etc/resolv.conf file for the default domain name and the 
Internet address of the initial hosts running the name server. 


Note: If the /etc/resolv.conf file does not exist, the res_init subroutine attempts name 
resolution using the local /etc/hosts file. If the system is not using a domain name 
server, the /etc/resolv.conf file should not exist. The /etc/host file should be 
present on the system even if the system is using a name server. In this instance, 
the file should contain the host ids that the system requires to function even if the 
name server is not functioning. 


The res_init subroutine is one of a set of subroutines that form the resolver, a set of 
functions that translate domain names to Internet addresses. All resolver subroutines use 
the /usr/include/resolv.h header file, which defines the _res structure. The res_init 
subroutine stores domain name information in the _res structure. 


implementation Specifics 


Files 


The res_init subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the res_init subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


/etc/resolv.conf Contains the name server and domain name. 


/etc/hosts Contains host names and their addresses for hosts 
in a network. This file is used to resolve a host 
name into an Internet address. 


/usr/include/arpa/nameser.h Contains the Internet name server. 

/usr/include/netinet/in.h Contains Internet constants and structures. 

/usr/include/resolv.h Contains global information used by the resolver 
subroutines. 

/usr/include/sys/types.h Contains definitions of unsigned data types. 
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Related Information 
Domain name access subroutines are the res_mkquery subroutine and res_send 
subroutine. 


Domain name translation subroutines are the dn_comp subroutine, dn_expand subroutine. 
dn_find subroutine, and dn_skipname subroutine. 


Byte stream and byte boundary retrieval subroutines are the _getlong subroutine, 
_getshort subroutine, putlong subroutine, and putshort subroutine. 
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res _mkquery Subroutine 


Purpose 
Makes query messages for name Servers. 


Library 
(libc.a) 


Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 


int res_mkquery (Operation, DomName, Class, Type, Data, DataLength, Reserved, 
Buffer, BufferLength) 

int Operation; 

char *DomName; 

int Class, Type; 

char * Data; 

int DataLength; 

struct rrec * Reserved; 

char * Buffer; 

int BufferLength; 


Description 
The res_mkquery subroutine makes packets for name servers in the Internet domain. The 
res_mkquery subroutine makes a standard query message and places this message in the 
location pointed to by the Buffer parameter. 


The res_mkquery subroutine is one of a set of subroutines that form the resolver, a set of 
functions that resolve domain names. Global information that is used by the resolver 
subroutines is kept in the _res data structure. The /include/resolv.h file contains the _res 
structure definition. 


Parameters 


Operation Specifies a query type. The usual type is QUERY, but the parameter can 
be set to any of the query types defined in the arpa/nameser.h file. 


DomName Points to the name of the domain. If the DomName parameter points to a 
single label and the RES_DEFNAMES bit is set, as it is by default, the 
subroutine appends DomName to the current domain name. The current 
domain name is defined by the name server in use or in the 
letc/resolv.conf file. 


Sockets 8—93 


res _mkquery 


8-94 


Class Specifies one of the following parameters: 


C_IN 


Specifies the ARPA Internet. 


C_CHAOS Specifies the Chaos network at MIT. 
Type Requires one of the following values: 
| TA Host address 
T_NS Authoritative server 
T_MD Mail destination 
T_MF Mail forwarder 
T_CNAME Canonical name 
T_SOA Start of authority zone 
T_MB Mailbox domain name 
T_MG Mail group member 
T_MR Mail rename name 
T_NULL NULL resource record 
T_WKS Wellknown service 
T_PTR Domain name pointer 
T_HINFO Host information 
T_MINFO Mailbox information 
T_MX _ Mail routing information 
T_UINFO User (finger) information 
T_UID User ID 
T_GID Group ID. 


Data 


DataLength 


Reserved 


Buffer 


Points to the data that is sent to the name server as a search key. The data 
is stored as a character array. 


Defines the size of the array pointed to by the Data parameter. 
Specifies a reserved and currently unused parameter. 


Points to a location containing the query message. 


BufferLength Specifies the length of the message pointed to by the Buffer parameter. 
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Return Value 
Upon successful completion, the res_mkquery subroutine returns the size of the query. If 
the query is larger than the value of the BufferLength parameter, the subroutine fails and 
returns a value of -1 (negative one). 


Implementation Specifics 
The res_mkquery subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the res_mkquery subroutine must be compiled with BSD 
defined. In addition, when applicable, all socket applications must include the BSD library 


libbsd. 

Files 
/etc/resolv.conf Contains the name server and domain name. 
/usr/include/resolv.h Contains global information used by the resolver 

subroutines. 

/usr/include/arpa/nameser.h Contains Internet name servers. 
/usr/include/sys/types.h Contains definitions of unsigned data types. 
/usr/include/netinet/in.h Contains Internet constants and structures. 


Related Information 
Domain name access subroutines are the res_init subroutine and res_send subroutine. 


Domain name translation subroutines are the dn_comp subroutine, dn_expand subroutine, 
dn_find subroutine, and dn_skipname subroutine. 


Byte stream and byte boundary retrieval subroutines are the _getlong subroutine, 
_getshort subroutine, putlong subroutine, and putshort subroutine. 
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res send Subroutine 


Purpose 
Sends a query to a name server and retrieves a response. 
Library 
(libc.a) 
Syntax 
#include <sys/types.h> 
#include <netinet/in.h> 
#include <arpa/nameser.h> 
#include <resolv.h> 
int res_send (MessagePtr, Messagelength, Answer, AnswerLength) 
char *MsgPtr, 
int MsgLength; 
char *Answer, 
int AnswerLength; 
Description 
The res_send subroutine sends a query to name servers and calls the res_init subroutine if 
the RES_INIT option of the _res structure is not set. This subroutine sends the query to the 
local name server and handles timeouts and retries. 
The res_send subroutine is one of a set of subroutines that form the resolver, a set of 
functions that resolve domain names. Global information that is used by the resolver 
subroutines is kept in the _res structure. The /include/resolv.h file contains the _res 
structure definition. 
Parameters 
MessagePtr Points to the beginning of a message. 
MessageLength Specifies the length of the message. 
Answer Points to an address where the response is stored. 
AnsLength Specifies the size of the answer area. 


Return Value 
Upon successful completion, the res_send subroutine returns the length of the message. 


If the res_send subroutine fails, the subroutine returns a —1 (negative one). 
Implementation Specifics 
The res_send subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the res_send subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 
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Files 

/etc/resolv.conf Contains general name server and domain name 
information. 

/usr/include/resolv.h Contains global information used by the resolver 
subroutines. 

/usr/include/arpa/nameser.h Contains general Internet name server information. 

/usr/include/sys/types.h Contains definitions of unsigned data types. 

/usr/include/netinet/in.h Contains Internet constants and structures. 


Related Information 
Domain name access subroutines are the res_init subroutine and res_mkquery subroutine. 


Domain name translation subroutines are the dn_comp subroutine, dn_expand subroutine, 
dn_find subroutine, and dn_skipname subroutine. 


Byte stream and byte boundary retrieval subroutines are the _getlong subroutine, 
_getshort subroutine, putlong subroutine, and putshort subroutine. 
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rexec Subroutine 


Purpose 


Library 


Syntax 


Allows command execution on a remote host. 


(libc.a) 


int rexec (Host, Port, User, Passwd, Command, ErrFileDescParam) 
char **Host; 

int Port; char *User, *Passwad, *Command; 

int *ErrFileDescParam; 


Description 


The rexec (remote execution) subroutine allows the calling process to execute commands 
on a remote host. 


If the rexec connection succeeds, a socket in the Internet domain of type SOCK_STREAM 
is returned to the calling process and is given to the remote command as standard input and 
standard output. 


Parameters 


8-98 


Host Contains the name of a remote host that is listed in the /etc/hosts file or 
/etc/resolv.config file. If the name of the host is not found in either file, the 
rexec fails. 


Port Specifies the well-known DARPA Internet port to use for the connection. A 
pointer to the structure that contains the necessary port can be obtained by 
issuing the following library call: 


getservbyname(“exec”,“tcp”) 


Userand Passwd 


Points to a user ID and password valid at the host. If these parameters are 
not supplied, the rexec subroutine takes the following actions until finding a 
user ID and password to send to the remote host: 


1. Searches the current environment for the user ID and password on the 
remote host. 


2. Searches the user’s home directory for a file called $HOME/.netre that 
contains a user ID and password. 


3. Prompts the user for a user ID and password. 
Command Points to the name of the command to be executed at the remote host. 


ErrFileDescParam 
Specifies one of the following values: 


e Not 0 (zero) = an auxiliary channel to a control process is set up, anda 
descriptor for it is placed in the ErrFileDescParam parameter. The 
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control process provides diagnostic output from the remote command on 
this channel and also accepts bytes as signal numbers to be forwarded to 
the process group of the command. This diagnostic information does not 
include remote authorization failure, since this connection is set up after 
authorization has been verified. 


e 0 (zero) = the standard error of the remote command is the same as 
standard output, and no provision is made for sending arbitrary signals to 
the remote process. In this case, however, it may be possible to send 
out—of—band data to the remote command. 


Return Value 
Upon successful completion, the system returns a socket to the remote command. 


lf the rexec subroutine is unsuccessful, the system returns a —1 (negative one) indicating 
that the specified host name does not exist. 


Implementation Specifics 
The rexec subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the rexec subroutine must be compiled with BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 


/etc/hosts Contains host names and their addresses for hosts ina 
network. This file is used to resolve a host name into an 
Internet address. 


/etc/resolv.config Contains the name server and domain name. 
$HOME/.netrc Contains Automatic login information. 


Related Information 
The rexecd command. 
The getservbyname subroutine. 


Additional remote command execution subroutines are the remd subroutine, rresvport 
subroutine, and ruserok subroutine. 
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rresvport Subroutine 


Purpose 
Retrieves a socket with a privileged address. 
Library 
(libc.a) 
Syntax 
int rresvport (Port) 
int *Port; 
Description 
The rresvport subroutine obtains a socket with a privileged address bound to the socket. A 
privileged Internet port is one that falls in the range of 0 to 1023. 
Only processes with an effective user ID of root user can use the rresvport subroutine. An 
authentication scheme based on remote port numbers is used to verify permissions. 
If the connection succeeds, a socket in the Internet domain of type SOCK_STREAM is 
returned to the calling process. 
Parameters 


Port Specifies the port to use for the connection. 


Return Values 


Upon successful completion, the rresvport subroutine returns a valid, bound socket 
descriptor. 


If the rresvport subroutine fails, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program. 
e Moves an error code, indicating the specific error, into the global variable errno 


Error Codes 
The rresvport subroutine fails if any one of the following errors occur: 


EAGAIN All network ports are in use. 

EAFNOSUPPORT 
The addresses in the specified address family cannot be used with this 
socket. 

EMFILE Two hundred (200) file descriptors are currently open. 

ENFILE The system file table is full. 

ENOBUFS Insufficient buffers are available in the system to complete the subroutine. 
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Implementation Specifics 
The rresvport subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the rresvport subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


File 


/etc/services Contains the service names. 


Related Information | 
Additional remote command execution subroutines are the remd subroutine and ruserok 
subroutine. 
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ruserok Subroutine 


Purpose 
The ruserok subroutine allows servers to authenticate clients. 
Library 
(libc.a) 
Syntax 
int ruserok (Host, RootUser, RemoteUser, LocalUser) 
char *Host; 
int RootUser, 
char *RemoteUser, *LocalUser, 
Description 
The ruserok (remote command user OK) subroutine allows servers to authenticate clients 
requesting services. 
Always specify the host name. If the local domain and remote domain are the same, 
specifying the domain parts is optional. To determine the domain of the host, use the 
gethostname subroutine. 
Parameters 


Host Specifies the name of a remote host. The ruserok subroutine checks for 
this host in the /etc/host.equiv file. Then, if necessary, the subroutine 
checks a file in the user’s home directory at the server called 
/$HOME/.rhosts for a host and remote user ID. 


RootUser Specifies a value to indicate whether the effective user ID of the calling 
process is that of a root user. A value of 0 (zero) indicates the process 
does not have a root user ID. A value of 1 (one) indicates that the 
process has local root user privileges, and the /ete/host.equiv file is not 
checked. 


RemoteUser Points to a user name that is valid at the remote host. Any valid user 
name can be specified. 


LocalUser Points to a user name that is valid at the local host. Any valid user name 
can be specified. 


Return Values 


The ruserok subroutine returns a 0 (zero), if the subroutine successfully locates the name 
specified by the Host parameter in the /etc/hosts.equiv file or the IDs specified by the Host 
and RemoteUser parameters are found in the /SHOME/.rhosts file. 


If the name specified by the Host parameter was not found, the ruserok subroutine returns 
a—1 (negative one). 
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Implementation Specifics 
The ruserok subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the ruserok subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/services Contains service names. 
/etc/host.equiv Specifies foreign host names. 
/SHOME/.rhosts Specifies the remote users of a local user account. 


Related Information 
Additional remote command execution subroutines are the remd subroutine and rresvport 
subroutine. 


subroutines to get and set the host name, respectively, are the gethostname subroutine and 
sethostname subroutine. 


TCP/IP Interface Program commands are the rlogind command and rshd command. 
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send Subroutine 


Purpose 
Sends messages from a connected socket. 


Syntax 
#include <sys/types.h> 
#include <sys/socketvar.h> 
#include <sys/socket.h> 
int send (Socket, Message, Length, Flags) 
int Socket; 
char *Message; 
int Length, Flags; 


Description 


The send subroutine sends a message only when the socket is connected. The sendto and 
sendmsg subroutines can be used with unconnected or connected sockets. 


To broadcast on a socket, first issue a setsockopt subroutine using the SO_BROADCAST 
option to gain broadcast permissions. 


Specify the length of the message with the Length parameter. If the message is too long to 


pass through the underlying protocol, the system returns an error and does not transmit the 
message. 


No indication of failure to deliver is implied in a send subroutine. A return value of —1 
(negative one) indicates some locally detected errors. 


If no space for messages is available at the sending socket to hold the message to be 
transmitted, the send subroutine blocks unless the socket is in a nonblocking I/O mode. 
Use the select subroutine to determine when it is possible to send more data. 


Parameters 
Socket Specifies the unique name for the socket. 
Message Points to the address of the message to send. 


Length Specifies the length of the message in bytes. 


Flags Allows the sender to control the transmission of the message. The Flags 


_. parameter to send a call is formed by logically ORing one or both of the 
values shown in the following list: 


MSG_OOB Processes out-of-band data on sockets 
that support SOCK_STREAM 
communication. 


MSG_DONTROUTE - Sends without using routing tables. 


The /sys/socket.h file defines the Flags values. 
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Return Value 
Upon successful completion, the send subroutine returns the number of characters sent. 


If the send subroutine fails, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 
e Moves an error code, indicating the specific error, into the global variable errno 


Error Codes 
The subroutine fails if any one or of the following errors occurs: 


EBADF The Socket parameter is not valid. 

ENOTSOCK The Socket parameter refers to a file, not a socket. 

EFAULT The Address parameter is not in a writable part of the user address 
space. 

EMSGSIZE The message is too large be sent all at once, as the socket 
requires. 

EWOULDBLOCK The socket is marked nonblocking, and no connections are present 


to be accepted. 


Implementation Specifics 
The send subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the send subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/types.h Contains definitions of unsigned data type. 


Related Information 
Subroutines to receive and send data over sockets are the recv subroutine, recvfrom 
subroutine, recvmsg subroutine, sendmsg subroutine, sendto subroutine, and shutdown 
subroutine. 


Socket creation and connection subroutines are the connect subroutine and socket 
subroutine. 


Subroutines for monitoring data broadcasts and manipulating socket options are the 
getsockopt subroutine, select subroutine, and setsockopt subroutine. 
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sendmsg Subroutine 


Purpose 
Sends a message from a socket using a message structure. 


Syntax 
#include<sys/types.h> 
#include <sys/socketvar.h> 
#include <sys/socket.h> 


int sendmsg (Socket, Message, Flags) 
int Socket; 

struct msghdr Message ]; 

int Flags; 


Description 


The sendmsg subroutine sends messages through connected or unconnected sockets 
using the msghdr message structure. The /sys/socket.h file contains the msghdr 
structure and defines the structure members. 


To broadcast on a socket, the application program must first issue a setsockopt subroutine 
using the SO_BROADCAST option to gain broadcast permissions. 


Parameters 
Socket Specifies the socket descriptor. 


Message Points to the msghdr message structure containing the message to be 


sent, the message length, the destination address, and the size of the 
destination address. 


Flags Allows the sender to control the message transmission. The /sys/socket.h 
file contains the Flags values. The Flags value to send a call is formed by 
logically ORing one or both of the following values: 


MSG_OOB Processes out—of—band data on sockets that 
support SOCK_STREAM. 


Note: The following value is not for general use. It is an administrative 
tool used for debugging or for routing programs. 


MSG_DONTROUTE Sends without using routing tables. 


Return Value 


Upon successful completion, the sendmsg subroutine returns the number of characters 
sent. | 


If the sendmsg subroutine fails, the system handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable errno 


8-106 Base Operating System Reference 


sendmsg 


Error Codes 


The sendmsg subroutine fails if any one of the following errors occurs: 


EBADF The Socket parameter is not valid. 

ENOTSOCK The Socket parameter refers to a file, not a socket. 

EMSGSIZE The message is too large to be sent all at once, as the socket 
requires. 

EWOULDBLOCK The socket is marked nonblocking, and no connections are present 


to be accepted. 


Implementation Specifics 


Files 


The sendmsg subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the sendmsg subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


/usr/include/sys/socket.h Contains socket definitions. 

/usr/include/sys/socketvar.h Defines the kernel structure per socket and 
contains buffer queues. 

/usr/include/sys/types.h Contains definitions of unsigned data types. 


Related Information 


Subroutines to receive and send data over sockets are the recv subroutine, recvfrom 
subroutine, recvmsg subroutine, send subroutine, sendto subroutine, and shutdown 
subroutine. 


Subroutines are to create sockets, the socket subroutine; to monitor data broadcasts, the 
select subroutine; to manipulate socket options, the getsockopt subroutine and 
setsockopt subroutine. 


Sockets Overview, Understanding Socket Data Transfer in Communications Programming 
Concepts. 


Sockets 8—107 


sendto 


sendto Subroutine 


Purpose 


Syntax 


Sends messages through a socket. 


#include <sys/types.h> 

#include <sys/socket.h> 

int sendto (Socket, Message, Length, Flags, To, ToLength) 
int Socket; 

char *Message; 

int Length, Flags; 

struct sockaddr *7o; 

int ToLength; 


Description 


The sendto subroutine allows an application program to sends messages through an 
unconnected sockets by specifying a destination address. 


To broadcast on a socket, first issue a setsockopt subroutine using the SO_BROADCAST 
option to gain broadcast permissions. 


Provide the address of the target using the 7o parameter. Specify the length of the message 
with the Length parameter. If the message is too long to pass through the underlying 
protocol, the error EMSGSIZE is returned and the message is not transmitted. 


lf the sending socket has no space to hold the message to be transmitted, the sendto 
subroutine blocks the message unless the socket is in a nonblocking I/O mode. 


Use the select subroutine to determine when it is possible to send more data. 


Parameters 
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Socket Specifies the unique name for the socket. 
Message Specifies the address containing the message to be sent. 
Length Specifies the size of the message in bytes. 


Flags Allows the sender to control the message transmission. The Flags value to 
send a call is formed by logically ORing one or both of the following values: 


MSG_OOB Processes out—of—band data on sockets that 
support SOCK_STREAM. 


Note: The following value is not for general use. 
MSG_DONTROUTE Sends without using routing tables. 


The /sys/socket.h file defines the Flags arguments. 
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To Specifies the destination address for the message. The destination address 
is a sockaddr structure defined in the /sys/socket.h header file. 


ToLength Specifies the size of the destination address. 


Return Value 


Upon successful completion, the sendto subroutine returns the number of characters sent. 


If the sendto subroutine fails, the system returns a value of —1 (negative one), and errno is 
set to indicate the error. 


Error Codes 


Examples 


The subroutine fails if any one of the following errors occurs: 


EBADF The Socket parameter is not valid. 

ENOTSOCK The Socket parameter refers to a file, not a socket. 

EFAULT The Address parameter is not in a writable part of the user address 
space. 

EMSGSIZE The message is too large be sent all at once, as the socket 
requires. 

EWOULDBLOCK The socket is marked nonblocking, and no connections are present 


to be accepted. 


1. The Sending UNIX Domain Datagrams program fragment illustrates the use of the 
sendto subroutine. 


2. The Sending Internet Domain Datagrams program fragment illustrates the use of the 
sendto subroutine. 


Implementation Specifics 


Files 


The sendto subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the sendto subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


/usr/include/sys/socket.h Contains socket definitions. 

/usr/include/sys/socketvar.h Defines the kernel structure per socket and 
contains buffer queues. 

/usr/include/sys/types.h Contains definitions of unsigned data types. 


Related Information 


Subroutines to receive and send data over sockets are the recv subroutine, recvfrom 


subroutine, recvmsg subroutine, send subroutine, sendmsg subroutine, and shutdown 
subroutine. 


Subroutines are: to create sockets, the socket subroutine; to monitor data broadcasts, 


select subroutine; to manipulate socket options, the getsockopt subroutine and 
setsockopt subroutine. 
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setdomainname Subroutine 


Purpose 
Sets the name of the current domain. 

Syntax 
int setdomainname ( name, namelen) 
char *name; 
int namelen; 

Description 
The setdomainname subroutine sets the name of the domain for the host machine. It is 
normally used when the system is bootstrapped. You must have root user authority to run 
this subroutine. 
The purpose of domains is to enable two distinct networks that may have host names in 
common to merge. Each network would be distinguished by having a different domain name. 
At the current time, only the NIS and the sendmail command make use of domains 
Note: Domain names are restricted to 64 characters. 

Parameters 
name Specifies the domain name to be set. 
namelen Specifies the size of the array pointed to by the name parameter. 


Return Values 
If the call suceeds, a value of 0 (zero) is returned. If the call fails, a value of —1 is returned 
and an error code is placed in the global location errno. 


Error Codes 
The following error may be returned by this subroutine: 
EFAULT The name parameter gave an invalid address. 
EPERM The caller was not the root user. 
Implementation Specifics 
The setdomainname subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the setdomainname subroutine must be compiled with _BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


Related Information 
The getdomainname subroutine, gethostname subroutine, sethostname subroutine. 
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sethostent Subroutine 


Purpose 
Opens network host file. 
Library 
(libe.a) 
Syntax 
#include <netdb.h> 
void sethostent (StayOpen) 
int StayOpen; 
Description 
The sethostent (set host entry) subroutine opens the /etc/hosts file and resets the file 
marker to the beginning of the file. 
Passing a nonzero value to the StayOpen parameter establishes a connection with a name 
server and allows a client process to retrieve one entry at a time from the /etc/hosts file. 
The client process can close the connection with the endhostent subroutine. 
Parameter 


StayOpen Contains a value used to indicate when to close the host file. 


Specifying a value of 0 (zero) closes the /etc/hosts file after each call to the 
gethostbyname or gethostbyaddr subroutine. 


Specifying a nonzero value allows the /ete/hosts file to remain open after 
each call. 


Return Values 
If an error occurs or if the end of the file is reached, the sethostent subroutine returns a 
NULL (0) pointer to the calling program. The subroutine handler moves an error code, 


indicating the specific error, into the h_errno variable. The calling program must examine 
h_errno, to determine the error. 


Error Code 
The sethostent subroutine fails if the following is true: 


NO_RECOVERY This error code indicates an unrecoverable error. 


Implementation Specifics 
The sethostent subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the sethostent subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 
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Files 
/etc/hosts Contains the host name database. 
/etc/resolv.conf Contains the name server and domain name. 
/usr/include/netdb.h Contains the network database structures. 


Related Information 
Additional host information retrieval subroutines are the endhostent subroutine, 
gethostbyaddr subroutine, and gethostbyname subroutine. 
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sethostid Subroutine 


Purpose 
Sets the unique identifier of the current host. 

Syntax 
intsethostid (HostID) 
int HostiD; 

Description 
The sethostid subroutine allows a calling process with a root user ID to set a new 32-bit 
identifier for the current host. The sethostid subroutine enables an application program to 
reset the host ID. 

Parameters 


HostiD Specifies the unique 32—bit identifier for the current host. 
Return Value 
Upon successful completion, the sethostid subroutine returns a value of O (zero). 
If the sethostid subroutine fails, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 
e Moves an error code, indicating the specific error, into the global variable errno 


Error Code 
The sethostid subroutine fails if the following is true: 


EPERM The calling process did not have an effective user ID of root user. 
Implementation Specifics 
The sethostid subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the sethostid subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Related Information | | 
Socket subroutines to obtain host names, IDs, and socket names, respectively, are the 
gethostid subroutine, gethostname subroutine, and getsockname subroutine. 
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sethostname Subroutine 


Purpose 
Sets the name of the current host. 


Syntax 
int sethostname (Name, NameLength) 
char *Name; 
int NameLength; 


Description 
The sethostname subroutine sets the name of a host machine. Only programs with a root 
user ID can use this subroutine. 


The sethostname subroutine allows a calling process with root user authority to set the 
internal host name of a machine on a network. 


Parameters 


Name Returns the address of an array of bytes where the host name is 
stored. 


NameLength Returns an integer that specifies the length of the Name array. 
Return Values 

Upon successful completion, the system returns a value of 0 (zero). 

If the sethostname subroutine fails, the subroutine handler performs the following functions: 

e Returns a value of —1 (negative one) to the calling program 

e Moves an error code, indicating the specific error, into the global variable errno 


Error Codes 3 
The sethostname subroutine fails if any one of the following errors occur: 


EFAULT The Name parameter or NameLength parameter gives an address that is 
not valid. 
EPERM The calling process did not have an effective root user ID. 


Implementation Specifics 
The sethostname subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the sethostname subroutine must be compiled with BSD 


defined. In addition, when applicable, all socket applications must include the BSD library 
libbsd. 


Sockets 8—115 


sethostname 


Related Information 


Socket subroutines to obtain and set the host ID are the gethostid subroutine and 
sethostid subroutine. 


The socket subroutine to obtain the host name is the gethostname subroutine. 


Sockets Overview, Understanding Network Address Translation in Communications 
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setnetent Subroutine 


Purpose 
Opens and rewinds the networks file. 
Library 
(libc.a) 
Syntax 
#include <netdb.h> 
void setnetent (StayOpen) 
int StayOpen; 
Description 
The setnetent (set network entry) subroutine opens the /etc/networks file and sets the file 
marker at the beginning of the file. 
Parameter 


StayOpen Contains a value used to indicate when to close the networks file. 


Specifying a value of 0 (zero) closes the networks file after each call to the 
getnetent subroutine. 


Specifying a nonzero values leaves the /etc/networks file open after each 
call. 


Return Values 
lf an error occurs or the end of the file is reached, the setnetent subroutine returns a NULL 
pointer. 


Implementation Specifics 
The setnetent subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the setnetent subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files | 
/etc/networks Contains official network names. 
/usr/include/netdb.h Contains the network database structures. 


Related Information 
Additional network information retrieval subroutines are the endnetent subroutine, 
getnetbyaddr subroutine, getnetbyname subroutine, and getnetent subroutine. 


Sockets Overview, Understanding Network Address Translation in Communications 
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setprotoent Subroutine 


Purpose 
Opens and rewinds the /etc/protocols file. 
Library 
(libc.a) 
Syntax 
#include <netdb.h> 
void setprotoent (StayOpen) 
int StayOpen; 
Description 
The setprotoent (set protocol entry) subroutine opens the /etc/protocols file and sets the 
file marker to the beginning of the file. 
Parameter 


StayOpen Indicates when to close the protocols file. 
Specifying a value of 0 (zero) closes the file after each call to getprotoent. 


Specifying a nonzero value allows the /etc/protocols file to remain open 
after each subroutine. 


Return Value 
The return value points to static data that is overwritten by subsequent calls. 


Implementation Specifics 
The setprotoent subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the setprotoent subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/protocols Contains the protocol names. 
/usr/include/netdb.h Contains the network database structures. 


Related Information 
Additional protocol information retrieval subroutines are the endprotoent subroutine, 
getprotobynumber subroutine, getprotobyname subroutine, and getprotoent subroutine. 


Sockets Overview, Understanding Network Address Translation in Communications 
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setservent Subroutine 


Purpose 
Gets service file entry. 
Library 
(libe.a) 
Syntax 
#include <netdb.h> 
void setservent (StayOpen) 
int StayOpen; 
Description 
The setservent (set service entry) subroutine opens the /etc/services file and sets the file 
marker at the beginning of the file. 
Parameters 


StayOpen Indicates when to close the services file. 


Specifying a value of 0 (zero) closes the file after each call to the 
getservent subroutine. 


Specifying a nonzero value allows the file to remain open after each call. 


Return Value 
lf an error occurs or the end of the file is reached, the setservent subroutine returns a NULL 
(0) pointer. 


Implementation Specifics 
The setservent subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the setservent subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/etc/services Contains service names. 
/usr/include/netdb.h Contains network database structures. 


Related Information 
Additional service information retrieval subroutines are the endservent subroutine, 
getservbyport subroutine, getservbyname subroutine,and getservent subroutine. 


Protocol information retrieval subroutines are the endprotoent subroutine, 
getprotobyname subroutine, getprotobynumber subroutine, getprotoent subroutine, and 
setprotoent subroutine. 
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setsockopt Subroutine 


Purpose 


Syntax 


Sets socket options. 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <sys/sockevar.h> 


int setsockopt (Socket, Level, OptionName, Option Value, OptionLength) 
int Socket, Level, OptionName; 

char *Option Value; 

int OptionLength; 


Description 


The setsockopt subroutine sets options associated with a socket. Options may exist at 
multiple protocol levels. The options are always present at the uppermost socket level. 


The setsockopt subroutine provides an application program with the means to control a 
socket communication. An application program can use the setsockopt subroutine to 
enable debugging at the protocol level, allocate buffer space, control timeouts, or permit 
socket data broadcasts. The /sys/socket.h file defines all the options available to the 
setsockopt subroutine. 


When setting socket options, specify the protocol level at which the option resides and the 
name of the option. 


Use the parameters OptionValue and OptionLength to access option values for the 
setsockopt subroutine. These parameters identify a buffer in which the value for the 
requested option or options is returned. 


Parameters 
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Socket Specifies the unique socket name. 
Level Specifies the protocol level at which the option resides. To set options at: 
Socket level specify Levelas SOL_SOCKET. 


Other levels supply the appropriate protocol number for the 
protocol controlling the option. For example, to 
indicate that an option will be interpreted by the TCP 
protocol, set Leve/ to the protocol number of TCP, as 
defined in the netinet/in.h file. 
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Specifies the option to set. The OptionName parameter and any 
specified options are passed uninterpreted to the appropriate protocol 
module for interpretation. The sys/socket.h header file defines the 
socket level options. The socket level options can be enabled or 
disabled; they operate in a toggle fashion. The options are: 


SO_DEBUG 


SO_REUSEADDR 


SO_KEEPALIVE 


SO_DONTROUTE 


SO_BROADCAST 
SO_LINGER 


SO_OOBINLINE 


Turns on recording of debugging 
information. This option enables or 
disables debugging in the underlying 
protocol modules. 


Specifies that the rules used in validating 
addresses supplied by a bind subroutine 
should allow reuse of local addresses. 


Keeps connections active. Enables the 
periodic transmission of messages ona 
connected socket. If the connected socket 
tails to respond to these messages, the 
connection is broken and processes using 
that socket are notified with a SIGPIPE 
signal. 


Does not apply routing on outgoing 
messages. Indicates that outgoing 
messages should bypass the standard 
routing facilities. Instead, they are directed 
to the appropriate network interface 
according to the network portion of the 
destination address. 


Permits sending of broadcast messages. 


Lingers on a close subroutine if data is 
present. This option controls the action 
taken when unsent messages queue on a 
socket and a close subroutine is 
performed. It uses a struct linger 
parameter defined in the sys/socket.h file. 
The parameter specifies the state of the 
option and linger interval. Specify the 
linger interval by using the setsockopt 
subroutine when requesting SO_LINGER. 


lf SO_LINGER is set, the system blocks 
the process during the close subroutine 
until it can transmit the data or until the time 
expires. lf SO_LINGER is not specified 
and a close subroutine is issued, the 
system handles the call in a way that allows 
the process to continue as quickly as 
possible. 


Leaves received out-of-band data (data 
marked urgent) in line. 
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OptionValue 


OptionLength 


SO_SNDBUF Sets send buffer size. 

SO_RCVBUF Sets receive buffer size. 
SO_SNDLOWAT Sets send low—water mark. 
SO_RCVLOWAT Sets receive low—water mark. 
SO_SNDTIMEO Sets send time out. 

SO_RCVTIMEO Sets receive time out. 

SO_ERROR Sets the retrieval of error status and clear 
SO_TYPE Sets the retrieval of a socket type. 


The Option Value parameter takes an /nt parameter. To enable a Boolean 
option, set the OptionValue parameter to a nonzero value. To disable an 
option, set the Option Value parameter to 0 (zero). 


The following options enable and disable in the same manner: 
SO_DEBUG 

SO_REUSEADDR 

SO_KEEPALIVE 

SO_DONTROUTE 

SO_BROADCAST 

SO_OOBINLINE 

SO_LINGER. 


The OptionLength parameter initially contains the size of the buffer 
pointed to by the OptionValue parameter. On return, the OptionLength 
parameter is modified to indicate the actual size of the value returned. If 
no option value is supplied or returned, the OptionVa/lue parameter can 
be 0 (zero). 


Options at other protocol levels vary in format and name. 


Return Value 


Upon successful completion, a value of 0 (zero) is returned. 


If the setsockopt subroutine fails, the subroutine handler performs the following functions: 


e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable errno 
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Error Codes 


Example 


The setsockopt subroutine fails if any one of the following errors occur: 


EBADF The Socket parameter is not valid. 

ENOTSOCK The Socket parameter refers to a file, not a socket. 
ENOPROTOOPT The option is unknown. 

EFAULT The Address parameter is not in a writable part of the user 


address space. 


1. To mark a socket for broadcasting: 


int on=1; 
setsockopt(s, SOL_SOCKET, SO BROADCAST, &on, sizeof(on)); 


implementation Specifics 


Files 


The setsockopt subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the setsockopt subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


/usr/include/sys/socket.h Contains socket definitions. 

/usr/include/sys/socketvar.h Defines the kernel structure per socket and 
contains buffer queues. 

/usr/include/sys/types.h Contains definitions of unsigned data types. 


Related Information 


The socket subroutine used for retrieving socket option data is the getsockopt subroutine. 


subroutines used for creating and naming sockets are, respectively, the bind subroutine and 
socket subroutine. 


Socket subroutines used to retrieve protocol data are the endprotoent subroutine, 
getprotobynumber subroutine, getprotoent subroutine, and setprotoent subroutine. 


Sockets Overview, Understanding Socket Options in Communications Programming 
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shutdown Subroutine 


Purpose 
Shuts down all socket send and receive operations. 
Syntax 
intshutdown (Socket, How) 
int Socket, How; 
Description 
The shutdown subroutine disables all receive and send operations on the specified socket. 
Parameters 
Socket Specifies the unique name of the socket 
How Specifies the type of subroutine shutdown. Use the following values: 
0 To disable further receive operations. 
1 To disable further send operations. 
2 To disable further send operations and receive operations. 


Return Values 
Upon successful completion, a value of 0 (zero) is returned. 


If the shutdown subroutine fails, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 
e Moves an error code, indicating the specific error, into the global variable errno 


Error Codes 
The shutdown subroutine fails if any one of the following errors occurs: 


EBADF The Socket parameter is not valid. 
ENOTSOCK The Socket parameter refers to a file, not a socket. 
ENOTCONN The socket is not connected. 


Implementation Specifics 
The shutdown subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the shutdown subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/sys/socket.h Contains socket definitions. 
/usr/include/sys/types.h Contains definitions of unsigned data types. 
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Related Information 
Subroutines to receive and send data over sockets are the read subroutine, recv subroutine, 
recvfrom subroutine, recvmsg subroutine, send subroutine, sendto subroutine, and write 
subroutine. 


Subroutines to create sockets, monitor data broadcasts, and manipulate socket options are 
the getsockopt subroutine, select subroutine, setsockopt subroutine, and socket 
subroutine. 
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socket Subroutine 


Purpose 


Syntax 


Creates an end point for communication and returns a descriptor. 


#include <sys/types.h> 
#include <sys/socket.h> 
#include <sys/socketvar.h> 


int socket (AddressFamily, Type, Protocol) 
int Domain, Type, Protocol; 


Description 


The socket subroutine creates a socket in the specified AddressFamily and of the specified 
Type. A protocol can be specified or assigned by the system. If the protocol is left 
unspecified (a value of 0), the system selects an appropriate protocol from those protocols in 
the address family that can be used to support the requested socket type. 


The socket subroutine returns a descriptor (an integer) that can be used in later subroutines 
that operate on sockets. 


Socket level options contro! socket operations. The getsockopt and setsockopt 


subroutines are used to get and set these options, which are defined in the sys/socket.h 
file. 


Parameters 
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AddressFamily Specifies an address family with which addresses specified in later socket 
operations should be interpreted. The /sys/socket.h file contains the 
definitions of the address families. Commonly used families are: 


AF_UNIX AIX path names 
AF_INET ARPA Internet addresses. 


Type Specifies the semantics of communication. The /sys/socket.h file defines 
the socket types. AIX supports the following types: 


SOCK_STREAM Provides sequenced, two-way byte streams with a 
transmission mechanism for out-of-band data. 


SOCK_DGRAM Provides datagrams, which are connectionless 
messages of a fixed maximum length (usually 
short). 


SOCK_RAW Provides access to internal network protocols and 


interfaces. This type of socket is available only to 
the root user. 


Protocol Specifies a particular protocol to be used with the socket. Specifying a 
Protocol of 0 (zero) causes the socket subroutine to default to the typical 
protocol for the requested type of returned socket. 
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Return Value 


Upon successful completion, the socket subroutine returns an integer (the socket » 
descriptor). 


lf the socket subroutine fails, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable errno. 


Error Codes 


Example 


The socket subroutine fails if any one of the following errors occurs:. 


EAFNOSUPPORT The addresses in the specified address family cannot be 
used with this socket. 

ESOCKTNOSUPPORT The socket in the specified address family is not supported. 

EMFILE The per—process descriptor table is full. 


ENOBUFS Insufficient resources were available in the system to 
complete the cail. 


1. The following program fragment illustrates the use of the socket subroutine to create a 
datagram socket for on—machine use. 


s = socket(AF_UNIX, SOCK _DGRAM,0); 


Implementation Specifics 


Files 


The socket subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the socket subroutine must be compiled with _BSD defined. In 
addition, when applicable, all socket applications must include the BSD library libbsd. 


/usr/include/sys/socket.h Contains socket definitions. 


/usr/include/sys/socketvar.h Defines the kernel structure per socket and 
contains buffer queues. 


/usr/include/sys/types.h Contains definitions for unsigned data types. 


Related Information 


Other socket creation and connection subroutines are the accept subroutine, bind 
subroutine, connect subroutine, listen subroutine, and socketpair subroutine. 


Subroutines for retrieving socket information and setting socket options are the 
getsockname subroutine, getsockopt subroutine, and setsockopt subroutine. 


Subroutines for receiving and sending data over sockets are the recv subroutine, recvfrom 
subroutine, recvmsg subroutine, send subroutine, sendto subroutine, sendmsg 
subroutine, and shutdown subroutine. 
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The ioctl subroutine and select subroutine. 


Sockets Overview, Understanding Socket Creation in Communications Programming 
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socketpair Subroutine 


Purpose 
Creates a pair of connected sockets. 


Syntax 
#include <sys/types.h> 
#include <sys/socket.h> 
#include <sys/socketvar.h> 


socketpair (Domain, Type, Protocol, SocketVector) 
int Domain, Type, Protocol; 
int SocketVector{2]; 


Description 
The socketpair subroutine creates an unnamed pair of connected sockets in a specified 


Domain, of a specified Type, and using the optionally specified Protocol. The two sockets 
are identical. 


Note: Create sockets with this subroutine only in the AF_UNIX domain. 


The descriptors used in referencing the new sockets are returned in SocketVector{0] and 
SocketVector{1]. 


The /sys/socket.h file contains the definitions for socket domains, types, and protocols. 


Parameters 


Domain Specifies the communications domain within which the sockets are 
created. This subroutine does not create sockets in the Internet domain. 


Type Specifies the communications method, whether SOCK_DGRAM or 
SOCK_STREAM, that the socket uses. 


Protocol Points to an optional identifier used to specify which standard set of rules 
(such as UDP/IP and TCP/IP) governs the transfer of data. 


SocketVector Points to a two—element vector that contains the integer descriptors of a 
pair of created sockets. 


Return Value 
Upon successful completion, the socketpair subroutine returns a value of 0 (zero). 
If the socketpair subroutine fails, the subroutine handler performs the following functions: 
e Returns a value of —1 (negative one) to the calling program 


e Moves an error code, indicating the specific error, into the global variable errno. 
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Error Codes 
The socketpair subroutine fails for any one of the following errors occurs: 


EMFILE This process has too many descriptors in use. 

EAFNOSUPPORT The addresses in the specified address family cannot be 
used with this socket. 

EPROTONOSUPPORT The specified protocol cannot be used on this system. 

EOPNOSUPPORT The specified protocol does not allow creation of socket 
pairs. 

EFAULT The SocketVector parameter is not in a writable part of the 


user address space. 
implementation Specifics 
The socketpair subroutine is part of AIX Base Operating System (BOS) Runtime. 


All applications containing the socketpair subroutine must be compiled with _BSD defined. 
In addition, when applicable, all socket applications must include the BSD library libbsd. 


Files 
/usr/include/sys/socket.h Contains socket definitions. 
/ust/include/sys/socketvar.h Defines the kernel structure per socket and 
contains buffer queues. 
/usr/include/sys/types.h Contains definitions for unsigned data types. 


Related Information 
An additional socket creation method is the socket subroutine. 


Sockets Overview, Understanding Socket Creation in Communications Programming 
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x25 _ack Subroutine 


Purpose 
Acknowledges data received with the D-bit set. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_ack( 
int conn_id 
); 
Description 
The x25_ack subroutine sends an acknowledgement for the data packet most recently 
received with the D-bit set for the call specified by conn_id. 
Control is returned to the calling application when the adapter has queued the packet for 
transmission. 
Parameter 


conn_id Connection identifier of the call. 


Return Value 
If successful, x25_ack returns a value of 0. If an error occurs, x25_ack returns —1 and sets 
x25_errno to one of the error codes shown below. 


Error Codes 
X25BADCONNID, X25NOACKREQ, X25NOCARD, X25NOLINK, X25NOTINIT, 
X25PROTOCOL, X25RESETCLEAR, X25SYSERR, X25TRUNCTX. 


If x25_errno is set to X25SYSERR, errno is set to one of the following values: 


EINTR, ElO, ENOSPC. 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_send subroutine. 
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x25_call Subroutine 


Purpose 
Makes an X.25 call, by setting up a switched virtual circuit (SVC). 

Library 
The X.25 Communications Library (libx25s.a) 

C Syntax 
int x25_call( 
struct cb_call_struct *cb_call, 
int ctr_id 

); 

Description 
The x25_cali subroutine sets up a switched virtual circuit (SVC) for the X.25 port specified in 
cb_call_struct, for an X.25 call between the calling address and called address, also 
specified in cb_call_ struct. 
Control is returned to the application as soon as the call-request packet has been 
transmitted, but the SVC is not actually established until a call-connected packet is received 
(using X25_receive). 
Optional facilities, such as fast-select calls, can be requested by entering the correct values 
in cb_fac_struct. If the facilities requested are not allowed by the network, the call is 
cleared and an appropriate error code is made available in cb_clear_struct, which can be 
received using x25_receive. 

Parameters 
cb_call Pointer to cb_call_ struct. 
ctr_id Identifier of a counter allocated by a previous x25_ctr_get. 


Return Value 


If successful, x25_call returns the connection identifier to be used by other subroutines for 
the duration of the call. If an error occurs, or the call is cleared, x25_call returns —1 and sets 
x25_errno to one of the error codes shown below. 


Error Codes 
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X25CALLED, X25CALLING, X25INVCTR, X25INVFAC, X25LONG, X25NOCARD, 


X25NOLINK, X25NOSUCHLINK, X25NOTINIT, X25PROTOCOL, X25SYSERR, 
X25TOOMANYVCS, X25TRUNCTX. 


If x25_errno is set to X25SYSERR, errno is set to one of the following values: 


EINTR, EIO, ENOSPC. 
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Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_call_accept and x25_call_clear subroutines. 
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x25_call_ accept Subroutine 


Purpose 
Accepts an incoming call. 


Library 
The X.25 Communications Library (libx25s.a) 


C Syntax 


int x25_call_accept( 

int conn_id, 

struct cb_call_struct *cb_call, 
int ctr_id 


); 
Description 3 
The x25_call_accept subroutine accepts an incoming call, by generating and sending a 
call-accepted packet. It then returns control to the application. If the facilities requested are 


not allowed by the network, the call is cleared and an appropriate error code is made 
available in a later cb_clear_struct control block. 


Parameters 
conn_id Connection identifier of the call 


cb_call Pointer to the call control block, cb_call_struct. 


ctr_id Identifier of a counter allocated by a previous x25_ctr_get, to be associated 
with this call. 


Return Value 
If successful, x25_call_ accept returns a value of 0. If an error occurs, x25_call_accept 
returns —-1 and sets x25_errno to one of the error codes shown below. 


Error Codes 
X25BADCONNID, X25CALLED, X25CALLING, X25INVCTR, X25INVFAC, X25LONG, 


X25NOCARD, X25NOLINK, X25NOTINIT, X25PROTOCOL, X25RESETCLEAR, 
X25SYSERR, X25TRUNCTX. 


If x25_errno is set to X25SYSERR, errno is set to one of the following values: 
EINTR, ElO, ENOSPC. 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information | 
The x25_call and x25_call_clear subroutines. 
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x25_call_clear Subroutine 


Purpose 
Clears a call. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_call_clear ( 
int conn_id, 
struct cb_clear_struct *cb_clear, 
struct cb_msg_struct *cb_msg 
); 
Description 
The x25_call_clear subroutine clears a call by generating and sending a clear-request 
packet. Control is not returned to the application until a clear-confirmation or a 
clear-indication packet has been received. 
The effect of clearing a call is to disconnect a connected call, or to reject a call that has not 
been accepted. 
Parameters 
conn_id Connection identifier of the call 
cb_clear Pointer to the clear structure, cb_clear_struct. 
cb_msg Pointer to the message structure, cb_msg_ struct. This structure is used to 


return information from the clear—confirmation packet. The application must 
interpret the appropriate structure to access the message. This structure is 
allocated by the API; it is the responsibility of the application to free this 
memory. If you set cb_msg value to NULL, no clear confirmation 
information is returned. 


Return Value 
If successful, x25_call_clear returns a value of 0. If an error occurs, x25_call_clear returns 
-1 and sets x25_ errno to one of the error codes shown below. 


Error Codes 
X25BADCONNID, X25CALLED, X25CALLING, X25LONG, X25NOCARD, X25NOLINK, 
X25NOTINIT, X25PROTOCOL, X25SYSERR, X25RESETCLEAR, X25TRUNCTX. 


lf x25_ errno is set to X25SYSERR, errno is set to one of the following values: 
EINTR, EIO, ENOSPC. 
Example 


Terminate (clear) a call: example program svexmit in Communications Programming 
Concepts. 
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Implementation Specifics 
| | This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_call and x25_call_accept subroutines. 
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x25_circuit_query Subroutine 


Purpose 
Returns configuration information about a virtual circuit. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
struct cb_circuit_info_struct *x25_circuit_query( 
int conn_id 
); 
Description 
The x25_circuit_query subroutine returns the current information about the specified virtual 
circuit in cb_circuit_info_ struct. | 
Parameter 


conn_id Connection identifier of the call currently using the virtual circuit. 


Return Values 
If successful, x25_circuit_query returns a pointer to cb_circuit_info_struct, the structure 
containing the information. Storage for this structure is allocated by the API; it is the 
responsibility of the application to free it. If an error occurs, x25_circuit_query returns NULL 
and sets x25_errno to one of the error codes shown below. 


Error Codes 
X25BADCONNID, X25NOLINK, X25NOTINIT, X25SYSERR. 
If x25_errno is set to X25SYSERR, errno is set to: 


ENOMEM 
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Example 
1. Print current information for the virtual circuit identified by conn_id. 


struct ¢b circuit info. strict: ect. ptr: 
ect_ptr = x25 circuit_query(conn_id); 


if (cct_ptr == NULL) 

(void)printf("Error %d from x25 circuit_query.”,x25 errno); 
else 
| 


if (cct_ptr —> flags & X25FLG LCN) 
(void)printf£("Logical Channel Number (LCN) : %d\n",cct_ptr —> 
den); 
if (cct_ptr —> flags & X25FLG INCOMING PACKET SIZE) 
(void)printf(”"Incoming Packet Size : %d\n”, 
ect_ptr —> incoming_packet_size); 
if (cct_ptr —> flags & X25FLG OUTGOING PACKET SIZE) 
(void)printf£(”"Outgoing Packet Size : %d\n”, 
cct_ptr —> outgoing packet_size); 
if (cct_ptr —> flags & X25FLG INCOMING THROUGHPUT_CLASS) 
(void)printf(”"Incoming throughput class : %d\n", 
cct_ptr —> incoming throughput_class); 
if (cct_ptr —> flags & X25FLG OUTGOING THROUGHPUT_CLASS) 
(void)printf("”Outgoing throughput class : %d\n”"”, 
cct_ptr —> outgoing _throughput_class); 
if (cct_ptr —> flags & X25FLG_INCOMING_WINDOW_SIZE) 
(void)printf("”Incoming window size : %d\n”, 
cct_ptr —> incoming_window_size) ; 
if (cct_ptr —> flags & X25FLG OUTGOING WINDOW SIZE) 
(void)printf(”Outgoing window size : %d\n”, 
ect_ptr —> outgoing _window_size); 


free(cct_ptr); 


} 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_device_query and x25_link_query subroutines. 
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x25_ctr_get Subroutine 


Purpose 

Gets a counter. 
Library 

The X.25 Communications Library (libx25s.a) 
C Syntax 

int x25_ctr_get( 

void 

) 

Description 


The x25_ctr_get subroutine allocates a counter whose value will be incremented whenever 
a message associated with it arrives and decremented whenever a message associated with 
it is received by an application. 


Return Value | 
If successful, x25_ctr_get returns the counter identifier. If an error occurs, x25_ctr_get 
returns —1 and sets x25_errno to one of the error codes shown below. 


Error Codes 
X25NOCTRS, X25NOTINIT, X25SYSERR. 


Example 
Get a counter: example program svcxmit in Communications Programming Concepts. 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_ctr_remove, x25_ctr_test and x25_ctr_wait subroutines. 
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x25 _ctr_remove Subroutine 


Purpose 
Removes a counter. 

Library 
The X.25 Communications Library (libx25s.a) 

C Syntax 
int x25_ctr_remove( 
int ctr_id 

); 

Description 
The x25_ctr_remove subroutine removes the specified counter from the system. The 
counter identifier may be reused by a future x25_ctr_get. Only the application that 
requested the counter can remove the counter from the system. The counter cannot be 
removed if it has a non-zero value, which indicates that some data is still waiting to be read 
from an associated call. 

Parameter 


ctr_id Identifier of a counter allocated by a previous x25_ctr_get. 


Return Values 
If successful, x25_ctr_remove returns 0. If an error occurs, x25_ctr_remove returns —1 and 
sets x25_errno to one of the error codes shown below. 


Error Codes 
X25AUTHCTR, X25CTRUSE, X25INVCTR, X25NOTINIT, X25SYSERR. 


Example 
Remove a counter: example program svcxmit in Communications Programming Concepts. 


Implementation Specifics 
This command is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_ctr_get, x25_ctr_test and x25_ctr_wait subroutines. 
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x25 ctr_test Subroutine 


Purpose 

Returns the current value of a counter. 
Library 

The X.25 Communications Library (libx25s.a) 
C Syntax 

int x25_ctr_test( 

int ctr_id 

); 

Description 

The x25_ctr_test subroutine returns the current value of an active counter, so that it can be 

tested. 
Parameter 


ctr_id Counter identifier allocated by a previous x25_ctr_get. 


Return Values 
If successful, x25_ctr_test returns the current value of the counter. If an error occurs, 
x25_ctr_test returns —1 and sets x25_errno to one of the error codes shown below. 


Error Codes 
X25INVCTR, X25NOTINIT, X25SYSERR. 


Example 
To find out how many messages for a call are waiting to be received, assuming we have an 
array of information about calls in our application: 
ctr_id = calls[i].counter_id; 
number of messages = x25 ctr_test(ctr_id); 
if (number_of messages != —-1) 
(void) printf(”The number of messages waiting is %d”, 
number_of messages); 


Note that the array used here is not part of the X.25 API. 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_ctr_get, x25_ctr_remove and x25_ctr_wait subroutines. 
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x25_ctr_wait Subroutine 


Purpose 
Waits for counters to change in value. 


Library 
The X.25 Communications Library (libx25s.a) 


C Syntax 
int x25_ctr_wait( 
int ctr_num, 
struct ctr_array_struct ctr_array[ ] 
) 
Description 
The x25_ctr_wait subroutine waits for the values of active counters to change in value. The 


process is suspended until the value of one of the counters is greater than the specified 
value. Setting this value in the application is optional, but recommended. 


Parameters 
ctr_num Number of elements in ctr_array_struct. 


ctr_array An array of structures containing: 
ctr_id Counter identifier allocated by a previous x25_ctr_get. 


ctr_value The value that must be exceeded by this counter. 


Return Values 
If successful, x25_ctr_wait returns the ctr_id of the counter that satisfied the condition by 
exceeding the specified value. (If more than one counter exceeded its specified value, only 


one of the counter identifiers is returned.) If an error occurs, x25_ctr_wait returns —1 and 
sets x25_errno to one of the error codes shown below. 


Error Codes 
X25INVCTR, X25NOTINIT, X25SYSERR. 


Examples 


1. Wait for a call to be connected (or cleared): example program svexmit in Communications 
Programming Concepts. 


2. Wait for an incoming call: example program svercv in Communications Programming 
Concepts. 


3. Wait for data (or some other message): example program svcrcv in Communications 
Programming Concepts. 
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Implementation Specifics 
This command is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_ctr_get, x25_ctr_remove and x25_ctr_test subroutines. 
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x25 deafen Subroutine 


Purpose 
Turns off listening. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_deafen( 
int listen_id 
); 
Description 
The x25_deafen subroutine turns off listening for incoming calls. !n other words, it stops 
routing the calls that this application was listening for using the specified listen_id. 
Parameter 


listen_id The listen identifier returned from a previous x25_listen. 


Return Values 
If successful, x25_deafen returns 0. If an error occurs, x25_deafen returns —1 and sets 
x25_errno to one of the error codes shown below. 


Error Codes 
X25BADLISTENID, X25NOTINIT, X25SYSERR, X25TIMEOUT. 


Example 
Stop listening: example program svercv in Communications Programming Concepts. 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_listen subroutine. 
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x25 _device_query Subroutine 


Purpose 
Returns configuration information about a device. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
struct cb_dev_info_struct *x25_device_query( 
struct cb_link_name_struct *link_name 
); 
Description 
The x25_device_query subroutine returns information about the X.25 adapter in 
cb_dev_info_ struct. 
The information returned is the information entered when you configured the adapter. 
Changes made to a particular switched virtual circuit (SVC) by requests entered in the 
facilities fields of X.25 API structures are not reflected by this subroutine; these values can 
be obtained by using the x25_circuit_query subroutine. 
Parameter 


link_name A pointer to cb_link_name_struct, which gives the name of the X.25 port. 


Return Values 
If successful, x25_device_query returns a pointer to cb_dev_info_struct, the structure 
containing the information. The storage for this structure is allocated by the API; it is the 
responsibility of the application to free it. If an error occurs, x25_device_query returns 
NULL and sets x25_errno to one of the error codes shown below. 


Error Codes 
X25NOTINIT, X25SYSERR. 


If x25_errno is set to X25SYSERR, errno is set to one of the following values: 
ENOMEM. 
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Example 
1. Print out the number of PVCs and the default and maximum packet sizes for an X.25 


port: 


struct cb_dev_info_struct *dev_ptr; 
dev_ptr = x25 device _query(&link_name) ; 
if (dev_ptr == NULL) 
(void)printf(”Error %¢d from x25 device_query.”,x25_ errno); 
else 


if (dev_ptr —> flags & X25FLG_NUA) 


{ 
(void)printf(”NUA : %s\n”,dev_ptr —> nua); 
free(dev_ptr —> nua); 
} 
if (dev_ptr —> flags & X25FLG_NO_OF_VCS) 
, (void)printf(”Number of PVCs : %d\n”,dev_ptr —> no_of_vcs); 
if (dev_ptr —> flags & X25FLG MAX RX PACKET SIZE) 
(void)printf("Max receive pkt size : %d\n”, 
dev_ptr —> max_rx_packet_size); 
if (dev_ptr —> flags & X25FLG MAX TX_ PACKET SIZE) 
(void)printf(”Max transmit pkt size :. sd\n", 
dev—ptr —> max_tx_packet_size); 
if (dev_ptr —> flags & X25FLG DEFAULT _SVC_RX_PACKET SIZE) 
(void)printf(”"Default receive pkt size : %d\n”, 
dev_ptr — default_svc_rx_packet_size); 
if (dev_ptr —> flags & X25FLG DEFAULT _SVC_TX_PACKET SIZE) 
(void)printf(”"Default transmit pkt size : %d\n”, 
dev_ptr —> default_svc_tx_packet_size); 


free(dev_ptr); 


} 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_circuit_query and x25_link_query subroutines. 
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x25_init Subroutine 


Purpose 
Initialize the X.25 application programming interface (API). 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_init( 
struct cb_link_name_struct *link_name 
); 
Description 
The x25_init subroutine sets up X.25 communications with the X.25 port named by 
link_name, by establishing communication with the X.25 device driver. The application must 
invoke x25_init before any other X.25 subroutines. Note that initializing a port does not 
guarantee that the port is connected (see x25_link_query and x25_link_connect). 
Parameter 


link_name A pointer to cb_link_name_struct, which gives the name of the X.25 port. 


Return Values | 
If successful, x25_init returns 0. If an error occurs, x25_init returns —1 and sets x25_errno 
to one of the error codes shown below. 


Error Codes 
X25BADDEVICE, X25INIT, X25MAXDEVICE, X25NOSUCHLINK, X25SYSERR. 


Example | 
Initialize the API for an X.25 port: example program svexmit in Communications 
Programming Concepts. 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_term subroutine. 
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x25 interrupt Subroutine 


Purpose 
Sends an interrupt packet. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_interrupt( 
int conn_id, 
struct cb_int_data_struct *cb_int 
) 
Description 
The x25_interrupt subroutine sends an interrupt message. Control is returned to the 
application when the message has been received by the adapter. 
Parameters 
conn_id Connection identifier of the call. 
cb_int Pointer to cb_int_data_struct, which contains the interrupt data. 


Return Values 
If successful, x25_interrupt returns 0. If an error occurs, x25_interrupt returns —1 and sets 
x25_errno to one of the error codes shown below. 


Error Codes 
X25BADCONNID, X25NOCARD, X25NOLINK, X25NOTINIT, X25PROTOCOL, 
X25RESETCLEAR, X25SYSERR, X25TRUNCTX. 


lf x25_errno is set to X25SYSERR, errno is set to one of the following values: 


EINTR, ElO, ENOSPC. 


Example 
1. Send an interrrupt: 


struct cb_int_struct int_data; 
int_data.flags = X25FLG_INT DATA; 
int_data.data_len = 20; 
int_data.int_data = "This is an interrupt”; 
re = x25_interrupt(conn_id,&int_data); 
if (re < 0) 
(void)printf(”Error %d from x25 _interrupt.”,x25_errno); 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


9-20 Base Operating System Reference 


x25_link_connect 


x25_link_connect Subroutine 


Purpose 
Connects an X.25 port to the X.25 network. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_link_connect( 
struct cb_link_name_struct *link_name 
); 
Description 
The x25_link_connect subroutine initializes the X.25 port. Control is returned to the calling 
application when communications have been established at link level. NET_CONFIG 
permission is required to use this subroutine. Note that the connection may take 30 seconds 
to complete. 
Parameter 


link_name A pointer to cb_link_name_struct, which gives the name of the X.25 port. 


Return Values 
If successful, x25_link_connect returns 0. If an error occurs, x25_link_connect returns —1 
and sets x25_errno to one of the error codes shown below. 


Error Codes 
X25AUTH, X25LINKUP, X25NOCARD, X25NOLINK, X25NOTINIT, X25SYSERR, 
X25TIMEOUT. | 


If x25_errno is set to X25SYSERR, errno is set to one of the following values: 
EINTR, EIO. 


Example 
1. Connect the x25s1 port to the network and print a message if an error occurs: 


struct cb_link_name_struct link_name; 

link_name.flags = X25FLG LINK NAME; 

link_name.link_ name = "x25s1"; 

re = x25 link _connect(&link_name); 

LE (re -< 0) 
(void)printf("Error ¢d occurred while connecting the link.”, 
x25 errno); 


implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_link_disconnect, x25_link_monitor, x25_link_statistics, and x25_link_query 
subroutines. 


The xmanage command. 
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x25 _link_disconnect Subroutine 


Purpose 
Disconnects an X.25 port. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_link_disconnect( 
struct cb_link_name_struct *link_name, 
int override 
); 
Description 
The x25_link_disconnect subroutine disconnects the X.25 port from the X.25 network. 
NET_CONFIG permission is required to use this subroutine. Note that the disconnection 
may take 30 seconds to complete. 
Parameters 


link_name A pointer to cb_link_name_struct, which gives the name of the X.25 port. 


override 0 means that the X.25 port is disconnected if all calls have been cleared and 


all permanent virtual circuits (PVCs) freed. 0 is assumed if the override 
parameter is not used. 


A value other than 0 means that the X.25 port is disconnected immediately. 
Set the override parameter to 1 if you want immediate disconnection. 


Return Values 
‘If successful, x25_link_disconnect returns 0. If an error occurs, x25_link_disconnect 
returns —1 and sets x25_errno to one of the error codes shown below. 


Error Codes 


X25AUTH, X25LINKUSE, X25NOCARD, X25NOLINK, X25NOTINIT, X25SYSERR, 
X25TIMEOUT. 


lf x25_errno is set to X25SYSERR, errno is set to one of the following values: 
EINTR, EIO. 

Examples 
1. Disconnect port x25s1 when all calls have been cleared: 


struct cb link _name_struct link_name; 
link_name.flags = X25FLG_ LINK_NAME; 


link_name.link_name = "x25s1"; 
override = 0; 
re = x25 link disconnect(&link_name,override) ; 


LE (ro =. 0) 
(void)printf(”Error %d from x25 link _disconnect.”,x25_ errno); 
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2. Disconnect port x25s2 without waiting for calls to be cleared: 


struct cb_link_name_struct link_name; 
link_name.flags = X25FLG LINK _NAME; 
link _name.link_name = ”x25s2"; 
override = 1; 
re = x25 link_disconnect(&link name,override); 
LF 0( re: <0) 
(void)printf(”Error %*d from x25 link disconnect.”,x25_ errno); 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_link_connect, x25_link_monitor, x25_link_statistics, and x25_link_query 
subroutines. 


The xmanage command. 
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x25_link_monitor Subroutine 


Purpose 
Controls monitoring of the activity on an X.25 port. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_link_monitor( 
struct cb_link_name_struct *link_name, 
long mode, 
int ctr_id 
); 
Description 
The x25_link_monitor subroutine turns on or off monitoring for an X.25 port. NET_CONFIG 
and RAS_CONFIG permissions are required to use this subroutine. The application must 
use the x25_ receive subroutine to get the monitoring data obtained by x25_link_monitor. 
Parameters 


link_name A pointer to cb_link_name_struct, which gives the name of the X.25 port. 


mode This consists of a long formed by ORing the values specified using the 
monitoring flags, X25_ MON PACKET and X25_MON_FRAME, which enable 
packet-level and frame-level monitoring respectively. If the mode is set to 0, 
both frame-level and packet-level monitoring are turned off. 


ctr_id Identifier of a counter allocated by a previous x25_ctr_get. Although you 
must pass this parameter, you need use it only if you want to wait for 
notification before receiving the monitoring data. 


Return Values 
If successful, x25_link_monitor returns the connection identifier of the channel on which the 


monitoring data must be received. If an error occurs, x25_link_monitor returns —1 and sets 
x25_errno to one of the error codes shown below. 


Error Codes 
X25INVMON, X25MONITOR, X25NOCARD, X25NOLINK, X25NOTINIT, X25SYSERR. 
If x25_errno is set to X25SYSERR, errno is set to one of the following values: 


EINTR, ElO, EPERM. 
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Examples 
1. Start monitoring port x25s1 at both packet-level and frame-level; then wait for and 


receive one packet of monitoring data: 


cb_ link _name.link_name = "x25s1"; 

ctr_id = x25ctr_get(); 

mode = X25 MON PACKET; /* For packet—level monitoring */ 
mode |= X25 MON FRAME; /* For frame—level monitoring */ 


conn_id = x25 link _monitor(&link_name,mode,ctr_id); 
if (conn_id < 0) 

(void)printf("Error %@d from x25 _link_monitor.”,x25 errno); 
else 


{ 


/* Wait for and receive a packet of monitoring data. */ 
ctr_array[0].ctr_id = ctr_id; 
ctr_array[0].ctr_value = 0; 


re 
re 


x25 ctr _wait(ctr_array,1); 
x25 receive(&conn_id,&cb_ msg); 


/* cb _msg will now contain relevant monitor information. */ 
L 
2. Stop monitoring port x25s1: 


cb_link_name.link_ name = ”"x25s1"; 
mode = 0; 
conn_id = x25 link _monitor(&link_name,mode,ctr_id); 
if (conn_id < 0) 
(void)printf("Error %d from x25_link_monitor.”,x25_ errno); 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_link_connect, x25_link_disconnect, x25_link_statistics, and 


x25_link_query subroutines. 


The xmonitor command. 
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x25 _link_query Subroutine 


Purpose 
Returns information about the current status of an X.25 port. 


Library 
The X.25 Communications Library (libx25s.a) 


C Syntax 
int x25_link_query( 
struct cb_link_name_struct *link_name 


Description 
The x25_link_query subroutine returns the status of the X.25 port as an integer. 


Parameter 
link_name A pointer to cb_link_name_struct, which gives the name of the X.25 port. 


Return Values 
If successful, x25_link_query returns an integer that indicates the status, one of 
X25_LINK_CONNECTED, X25_LINK_DISCONNECTED, X25_LINK_CONNECTING. If an 
error occurs, x25_link_query returns —1 and sets x25_errno to one of the error codes 
shown below. 


Error Codes 
X25NOCARD, X25NOTINIT, X25SYSERR. 


If x25_ errno is set to X25SYSERR, errno is set to one of the following values: 
EINTR, EIO. 
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Example 
1. Find out whether port x25s1 is connected, disconnected, or connecting: 


struct cb_link_name_struct link_name; 
link_name.flags = X25FLG LINK_NAME; 
link_name.link_name = "x25s1"; 

re = x25 link_query(&link_name) ; 
switch (rc) 


case X25 LINK _CONNECTED: 
(void)printf(”"Link is connected\n”"); 
break; 

case X25 LINK DISCONNECTED: 
(void)printf("Link is disconnected\n”); 
break; 

case X25 LINK_CONNECTING: 
(void)printf(”"Link is connecting\n”); 
break; 
case —1; 

switch (x25 errno); 


case X25SYSERR: 
(void)printf(”"System error : errno 
perror(); 
break; 

case X25NOCARD: 
(void)printf("The X.25 adapter is either not 

installed\n”); 

(void)printf(”or not functioning:”); 
(void)printf(”Call your system administrator.\n”); 


break; 


case X25NOTINIT: 
(void)printf("The application has not initialized\n”, 


(void)printf(”"X.25 communications:”); 
(void)printf(”"Call your system administrator.\n”); 


break; 


= ¢d\n”,errno); 


} 


break; 


} 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information , 
The x25_circuit_query, x25_device_query, x25_link_connect, x25_link_disconnect, 
x25_link_statistics, and x25_link_monitor subroutines. 


The xmanage command. 
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x25_link_statistics Subroutine 


Purpose 
Request statistics for an X.25 port. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
struct cb_link_stats_struct *x25_link_statistics( 
struct cb_link_name_struct *link_name, 
unsigned short reset 
); 
Description 
The x25_link stats subroutine obtains statistics about the X.25 activity on an X.25 port. 
Parameters 


link_name A pointer to cb_link_name_struct, which gives the name of the X.25 port. 


reset lf reset is set to 1, statistics are reset to 0. 


Return Values . 
If successful, x25_links_statistics returns a pointer to cb_link_stats_struct. The storage 
for cb_link_stats_struct is allocated by the API; it is the responsibility of the application to 
free it. If an error occurs, x25_link stats returns NULL and sets x25_errno to one of the 
error codes shown below. 


Error Codes 
X25NOCARD, X25NOTINIT, X25SYSERR. 


If x25_errno is set to X25SYSERR, errno is set to one of the following values: 
EINTR, EIO. 
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Example 
1. Find out the number of virtual circuits currently in use for a port: 


struct cb_link_stats_ struct *link_ptr; 


reset = 0; 
link_ptr = x25_link_statistics(&link_name, reset) ; 


if (link_ptr == NULL) 
(void)printf(”"Error *d from x25 _link_statistics.”,x25 errno); 


else 
if (link_ptr —> flags & X25FLG_NO_OF_VCS) 
(void)printf£("Number of virtual circuits : d\n”, 
link_ptr —> no_of_vcs); 


if (link_ptr —> flags & X25FLG _LINK_STATS) 
printf ("link statistics returned in x25 query data 


structure\n”); 


free(link_ptr); 
} 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_link_connect, x25_link_disconnect, x25_link_monitor, and x25_link_query 


subroutines. 
The xmanage command. 
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x25 _ listen Subroutine 


Purpose 

Starts listening for incoming calls. 

Library 
The X.25 Communications Library (libx25s.a) 

C Syntax 
int x25_listen( 
NLchar *name, 
int ctr_id 

)s 

Description 
The x25_listen subroutine tells the API that this application is interested in incoming calls 
that fit the criteria in the routing list entry that has the specified name. It also tells the API to 
associate such calls with the counter identifier specified. It returns a listen identifier to be 
used by x25_receive. 

Parameters 
name Pointer to a name that is specified in the routing list. 
ctr_id- Identifier of a counter, allocated by a previous x25_ctr_get. 


Return Values 
If successful, x25_listen returns the listen identifier. If an error occurs, x25_listen returns —1 
and sets x25_errno to one of the error codes shown below. 


Error Codes 
X25AUTHLISTEN, X25INVCTR, X25NAMEUSED, X25NOLINK, X25NONAME, 
X25NOTINIT, X25SYSERR, X25TABLE, X25TIMEOUT. 


Example 


Start listening for incoming calls: example program svercv in Communications Programming 
Concepts. 


Implementation Specifics | 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_deafen subroutine. 
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x25 pvc_alloc Subroutine 


Purpose 

Allocates a permanent virtual circuit (PVC) for use by an application. 
Library 

_ The X.25 Communications Library (libx25s.a) 

C Syntax 

int x25_pvc_alloc( 

struct cb_pvc_alloc_struct *pvc_ptr, 

int ctr_id 

); 

Description 

The x25_pvc_alloc subroutine reserves the use of the specified permanent virtual circuit 

(PVC) for this application only. 
Parameters 


pvc_ptr A pointer to cb_pvc_alloc_struct, which contains the name of the X.25 port 
and the logical channel number of the PVC to be used. (Together, these 
identify the PVC.) 


ctr_id Identifier of a counter allocated by a previous x25_ctr_get. 


Return Values 
If successful, x25_pve_alloc returns the connection identifier to be used by other 
subroutines. If an error occurs, x25_pvc_alloc returns —1 and sets x25_errno to one of the 
error codes shown below. 


Error Codes 
X25INVCTR, X25NOCARD, X25NOLINK, X25NOSUCHLINK, X25NOTINIT, X25NOTPVC, 
X25PVCUSED, X25SYSERR. 


If x25_ errno is set to X25SYSERR, errno is set to one of the following values: 


EINTR, EIO. 


Example 
Allocate a PVC: example program pvexmit in Communications Programming Concepts. 


implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_pvc_free subroutine. 


X.25 Application 9-31 


x25_pvc_free 


x25 _pvc_free Subroutine 


Purpose 
Frees a permanent virtual circuit (PVC). 

Library 
The X.25 Communications Library (libx25s.a) 

C Syntax 
int x25_pvc_free( ; 
int conn_id 

); 

Description 
The x25_pvc_free subroutine frees the permanent virtual circuit (PVC) used for the 
specified connection, so that it can be used by another application. Any data queued for 
x25_receive is lost. It is the responsibility of the application to check the counter identifier for 
queued data before freeing the PVC. 

Parameter 


conn_id Connection identifier, returned by the previous x25_pvc_alloc. 


Return Values 


If successful, x25_pve_free returns 0. If an error occurs, x25_pvc_free returns —1 and sets 
x25_errno to one of the error codes shown below. 


Error Codes 
X25BADCONNID, X25NOCARD, X25NOLINK, X25NOTINIT, X25SYSERR. 
If x25_errno is set to X25SYSERR, errno is set to one of the following values: 
EINTR, EIO. 


Example 
Free a PVC: example program pvcxmit in Communications Programming Concepts. 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_pvc_alloc subroutine. 
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x25_receive Subroutine 


Purpose 
Receives an incoming packet and indicates the packet type. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_receive( 
int *conn_id, 
struct cb_msg_struct *cb_msg 
); 
Description 
The x25_ receive subroutine is used to receive both incoming calls and messages or 
monitoring data for already-connected calls. One x25_receive receives a complete packet 
sequence. In the event of an interrupt packet being received, an interrupt confirmation is 
sent automatically by the system. 
Parameters 
conn_id To receive an incoming call, a pointer to an integer that contains the listen 
identifier. 


To receive a message for any already-connected call, a pointer to an integer 
that contains 0. 


To receive a message for a specific already-connected call, a pointer to an 
integer that contains the connection identifier of the call. 


To receive monitoring data for a call, a pointer to an integer that contains the 
connection identifier returned by x25_link_monitor. 


On return from this subroutine, in all cases, a pointer to an integer that now 
contains the actual connection identifier. 


cb_msg Pointer to the message structure, cb_msg_ struct, which includes the 


msg_type. This structure is allocated by the API; it is the responsibility of 
the application to free this memory. 


Return Value 


If successful, X25_receive returns a non-negative value. If an error occurs, x25_receive 
returns —1 and sets x25_ errno to one of the error codes shown below. 


Error Codes 


X25BADID, X25NOACK, X25NOCARD, X25NODATA, X25NOLINK, X25NOTINIT, 
X25RESETCLEAR, X25SYSERR, X25TRUNCTX. 


If x25_errno is set to X25SYSERR, errno is set to one of the following values: 


EINTR. 
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Examples 
1. Receive an incoming call: example program svercv in Communications Programming 
Concepts. 


2. Receive data (or some other message): example program svcrcv in Communications 
Programming Concepts. 


3. Receive an acknowledgment that data has been received: example program svexmit in 
Communications Programming Concepts. 


_Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_send subroutine. 
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x25_reset Subroutine 


Purpose 
Resynchronizes communications on a virtual circuit. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_reset( 
int conn_id, 
struct cb_res_ struct *cb res 
); 
Description 
The x25_reset subroutine sends out a reset-indication packet to reset the virtual circuit, 
using the specified connection identifier. 
If the application was sending any data at the time of calling this subroutine, the data is 
flushed from the system, and the x25_send subroutine returns an appropriate error code. 
Incoming data not already passed to the application will be flushed. As resets can cause 
data to be lost, it is the responsibility of the application to provide higher-level protocol to 
protect data. 
Parameters 
conn_id Connection identifier of the call. 
cb_res Pointer to cb_res_ struct, which is used to pass the reset cause and 


diagnostic codes. 


Return Values 
If successful, x25_reset returns 0. If an error occurs, x25_reset returns —1 and sets 
x25 _errno to one of the error codes shown below. 


Error Codes 
X25BADCONNID, X25NOCARD, X25NOLINK, X25NOTINIT, X25PROTOCOL, 
X25RESETCLEAR, X25SYSERR. 


If x25_errno is set to X25SYSERR, errno is set to one of the following values: 
EINTR, ElO, ENOSPC. 


Example | 
Reset a call: example program pvexmit in Communications Programming Concepts. 


implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_reset_confirm subroutine. 
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x25_reset_confirm Subroutine 


Purpose 
Confirms that a reset-indication has been received. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_reset_confirm( 
int conn_id, 
); 
Description 
The x25_reset_confirm subroutine sends a reset-confirmation packet. After an 
reset-indication packet has been received, by x25_ receive, no further data can be sent or 
received until the reset-confirmation has been sent. Any data currently in transmission is 
discarded with an appropriate return code. 
Parameter 


conn_id Connection identifier of the call. 


Return Values 
If successful, x25_reset_confirm returns 0. If an error occurs, x25_reset_confirm returns 
—1 and sets x25_errno to one of the error codes shown below. 


Error Codes 
EINTR, ElO, ENOSPC, X25BADCONNID, X25NOACK, X25NOCARD, X25NOLINK, 
X25NOTINIT, X25PROTOCOL, X25RESETCLEAR, X25SYSERR, X25TRUNCTX. 


Example 


Confirm that a reset indication has arrived: example program pvcrcv in Communications 
Programming Concepts. 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_reset subroutine. 
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x25 send Subroutine 


Purpose 
Sends a data packet. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_send( 
int conn_id, 
struct cb_data_struct *cb_data 
); 
Description 
The x25_send subroutine transfers the data packet to the adapter for transmission across 
the network. Control is returned to the calling application as soon as the device driver has 
indicated successful transferral of the data to the adapter. 
Parameters 
conn_id Connection identifier of the call. 
cb_data Pointer to data structure, cb_data_struct. 


Return Values 
If successful, x25_send returns 0. If an error occurs, x25_send returns —1 and sets 
x25_errno to one of the error codes shown below. 


Error Codes 
X25BADCONNID, X25NOACK, X25NOCARD, X25NOLINK, X25NOTINIT, 
X25PROTOCOL, X25RESETCLEAR, X25SYSERR, X25TRUNCTX. 


If x25_errno is set to X25SYSERR, errno is set to one of the following values: 
EFAULT, EINTR, ElO, ENOSPC. 
Examples 


1. Send data without the D-bit set: example program svexmit in Communications 
Programming Concepts. 


2. Send data with the D-bit set to request acknowledgment: example program svexmit in 
Communications Programming Concepts. 


Implementation Specifics 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_receive and x25_ack subroutines. 
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x25 term Subroutine 


Purpose 
Terminates the X.25 API for a specified X.25 port. 
Library 
The X.25 Communications Library (libx25s.a) 
C Syntax 
int x25_term( 
struct cb_link_name_ struct *link_name 
)s 
Description 
The x25_term subroutine stops X.25 communications with the X.25 port named by 
link_name, by terminating communication with the X.25 device driver. If this is the last X.25 
port open for this process, X.25 resources are freed. 
x25_term clears any virtual circuits that are still being used by the application. Nevertheless, 
you should clear the virtual circuits and tidy up in a controlled way before invoking 
x25 term. 
Parameter 


link_name A pointer to cb_link_name_struct, which gives the name of the X.25 port. 


Return Values 
If successful, x25_term returns 0. If an error occurs, x25_term returns —1 and sets 
x25 errno to one of the error codes shown below. 


Error Codes 
X25BADDEVICE, X25SYSERR. 


Example 
Terminate the API: example program svexmit in Communications Programming Concepts. 


Implementation Specifics | 
This subroutine is part of X.25 Application in AIX BOS Extensions 2. 


Related Information 
The x25_init subroutine. 
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SYS _CFGDD sysconfig Operation 


Purpose 
Calls a previously loaded device driver at its module entry point. 


Description 
The SYS_CFGDD sysconfig operation calls a previously loaded device driver at its module 
entry point. The device driver's module entry point, by convention, is its ddconfig entry 
point. The SYS_CFGDD operation is typically invoked by device configure or unconfigure 
methods to initialize or terminate a device driver, or to request device vital product data. 


The sysconfig subroutine puts no restrictions on the command code passed to the device 
driver. This allows the device driver’s ddconfig entry point to provide additional services, if 
desired. 


The parmp parameter on the SYS_CFGDD sysconfig operation points to a cfg_dd 
structure defined in the sys/sysconfig.h header file. The parmlen parameter on the 
sysconfig system call should be set to the size of this structure. 


If the kmid variable in the cfg_dd structure is 0, the desired device driver is assumed to be 
already installed in the device switch table. The major portion of the device number (passed 
in the devno field in the cfg_dd structure) is used as an index into the device switch table. 
The device switch table entry indexed by this devno field contains the device driver's © 

ddconfig entry point to be called. 


lf the kmid variable is not 0, it contains the module ID to use in calling the device driver. A 
uio structure is used to pass the address and length of the device—dependent structure, 
specified by the cfg_dd.ddsptr and cfg_dd.ddslen fields, to the device driver being called. 


The ddconfig device driver entry point provides information on how to define the ddconfig 
routine. 


The device driver to be called is responsible for using the appropriate routines to copy the 
device—dependent structure (DDS) from user to kernel space. 


Return Values 
If the SYS_CFGDD sysconfig operation successfully calls the specified device driver, the 
return code from the ddconfig routine determines the value returned by this subroutine. If 
the ddconfig routine's return code is 0, then the value returned by the sysconfig subroutine 
is 0. Otherwise the value returned is a —1, and the errno global variable is set to the return 
code provided by the device driver’s ddconfig routine. 


Errors detected by the SYS_CFGDD sysconfig operation result in the following values for 
the errno variable: 


EACESS The calling process does not have the required privilege. 


EFAULT The calling process does not have sufficient authority to access the data 
area described by the parmp and parmien parameters provided on the 
system call. This error is also returned if an I/O error occurred when 
accessing data in this area. 
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EINVAL Invalid module ID. 


ENODEV Module ID specified by the cfg_dd.kmid field was 0, and an invalid or 
undefined devno value was specified. 


Related Information 
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The sysconfig subroutine. 

The ddconfig device driver entry point. 
The Device Switch Table. 

The uio structure. 

The Device—Dependent (DDS) structure. 


Understanding Major and Minor Numbers For A Special File in Kernel Extensions and 
Device Support Programming Concepts. 


System Call Kernel Extension Overview in Kernel Extensions and Device Support 
Programming Concepts. 


Device Driver Kernel Extension Overview in Kernel Extensions and Device Support 
Programming Concepts. 


Virtual File System Introduction in Kernel Extensions and Device Support Programming 
Concepts. 


Device Configuration Subsystem: Programming Introduction in Kernel Extensions and 
Device Support Programming Concepts. 


Programming in the Kernel Environment in Kernel Extensions and Device Support 
Programming Concepts. 


Understanding Kernel Extension Binding in Kerne/ Extensions and Device Support 
Programming Concepts. 
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SYS_CFGKMD sysconfig Operation 


Purpose 
Invokes a previously loaded kernel object file at its module entry point. 


Description 
The SYS_CFGKMD sysconfig operation invokes a previously loaded kernel object file at its 
module entry point, typically for initialization or termination functions. The SYS_CFGDD 
operation performs a similar function for device drivers. 


The parmp parameter on the sysconfig subroutine points to a cfg_kmod structure, which is 
defined in the sys/sysconfig.h header file. The kmid field in this structure specifies the 
kernel module ID of the module to invoke. This value is returned when using the 
SYS_KLOAD or SYS_SINGLELOAD sysconfig operation to load the object file. 


The emd field in the cfg_kmod structure is a module—dependent parameter specifying the 
action that the routine at the module’s entry point should perform. This is typically used for 
initialization and termination commands after loading and prior to unloading the object file. 


The mdiptr field in the cfg_kmod structure points to a module—dependent structure whose 
size is specified by the mdilen field. This field is used to provide module—dependent 
information to the module to be called. If no such information is needed, the mdiptr field can 
be NULL. 


lf the mdiptr field is not NULL, then the SYS_CFGKMD operation builds a uio structure 
describing the address and length of the module—dependent information in the caller’s 
address space. The mdiptr and mdilen fields are used to fill in the fields of this uio 
structure. The module is then called at its module entry point with the cmd parameter and a 
pointer to the uio structure. If there is no module—dependent information to be provided, the 
uiop parameter passed to the module’s entry point is set to NULL. 


The module’s entry point should be defined as follows: 


int module_entry(cmd, uiop) 
int cmd; 
struct uio *uiop; 


The definition of the module—dependent information and its length is specific to the module 


being configured. The module to be called is responsible for using the appropriate routines 
to copy the module—dependent information from user to kernel space. 


Return Values 
If the kernel module to be invoked is successfully called, its return code determines the 
value that is returned by the SYS_CFGKMOD sysconfig operation. If the called module’s 
return code is 0, then the value returned by the sysconfig subroutine is 0. Otherwise the 
value returned is —1 and the errno global variable is set to the called module’s return code. 


Errors detected by the SYS_CFGKMOD sysconfig operation result in the following values 
for the errno variable: 


EINVAL Invalid module ID. 
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EACESS The calling process does not have the required privilege. 


EFAULT The calling process does not have sufficient authority to access the data 
area described by the parmp and parmien parameters provided on the 
system call. This error is also returned if an I/O error occurred when 
accessing data in this area. 


Related Information 
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The sysconfig subroutine. 


The SYS_CFGDD sysconfig subroutine, SYS_KLOAD sysconfig subroutine, 
SYS_SINGLELOAD sysconfig operation. 


The uio structure. 


System Call Kernel Extension Overview in Kernel Extensions and Device Support 
Programming Concepts. 


Device Driver Introduction in Kernel Extensions and Device Support Programming 
Concepts. 


Device Driver Kernel Extension Overview in Kernel Extensions and Device Support 
Programming Concepts. 


Virtual File System Introduction in Kernel Extensions and Device Support Programming 
Concepts. 


Device Configuration Subsystem: Programming Introduction in Kernel Extensions and 
Device Support Programming Concepts. 


Programming in the Kernel Environment in Kernel Extensions and Device Support 
Programming Concepts. 


Understanding Kernel Extension Binding in Kernel Extensions and Device Support 
Programming Concepts. 
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sysconfig Subroutine 


Purpose 
Provides a service for controlling system/kernel configuration. 
Syntax 
#include <sys/types.h> 
#include <sys/sysconfig.h> 
int sysconfig (cmd, parmp, parmlen) 
int cmd; 
void *parmp; 
int parmlen; 
Parameters 
cmd Specifies the function that the sysconfig subroutine is to perform. 
parmp Specifies a user-provided structure. 
parmlen Specifies the length of the user—provided structure indicated by the parmp 
parameter. 
Description 


The sysconfig subroutine is used to customize the AIX Operating System. This subroutine 
provides a means of loading, unloading, and configuring kernel extensions. These kernel 
extensions can be additional kernel services, additional system calls, device drivers, or file 
systems. The sysconfig subroutine also provides the ability to read and set system runtime 
operating parameters. 


Use of the sysconfig subroutine requires appropriate privilege. 


The particular operation that the sysconfig subroutine provides is defined by the value of 
the cmd parameter. The following operations are defined: 


SYS_KLOAD Loads a kernel extension object file into kernel memory. 


SYS_SINGLELOAD 
Loads a kernel extension object file only if it is not already loaded. 


SYS_QUERYLOAD 
Determines if a specified kernel object file is loaded. 


SYS KULOAD 
Unloads a previously loaded kernel object file. 


SYS_CFGKMOD 


Calls the specified module at its module entry point for configuration 
purposes. 


SYS_CFGDD Calls the specified device driver configuration routine (module entry point). 


SYS_QDVSW 
Checks the status of a device switch entry in the device switch table. 
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SYS_GETPARMS 
Returns a structure containing the current values of runtime system 
parameters found in the var structure. 

SYS_SETPARMS 
Sets runtime system parameters from a caller—provided structure. 


Loader Symbol Binding Support, described with the sysconfig SYS_KLOAD operation, 
explains the symbol binding support provided when loading kernel object files. 


Return Values 


These sysconfig operations return a value of 0 upon successful completion of the 
subroutine. Otherwise, a value of —1 is returned and the errno global variable is set to 
indicate the error. 


Any sysconfig operation requiring a structure from the caller fails if the structure is not 
entirely within memory addressable by the calling process. A return value of —1 is passed 
back and the errno global variable is set to EFAULLT. 


Related Information 


The ddconfig device driver entry point. 
Understanding the device switch table. 
Loader Symbol Binding Support in the SYS_KLOAD sysconfig operation. 


System Call Kernel Extension Overview in Kernel Extensions and Device Support 
Programming Concepts. 


Device Driver Kernel Extension Overview in Kernel Extensions and Device Support 
Programming Concepts. 


Virtual File System Introduction in Kernel Extensions and Device Support Programming 
Concepts. 


Device Configuration Subsystem: Programming Introduction in Kernel Extensions and 
Device Support Programming Concepts. 


Programming in the Kernel Environment in Kernel Extensions and Device Support 
Programming Concepts. 


Understanding Kernel Extension Binding in Kernel Extensions and Device Support 
Programming Concepts. 
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SYS_GETPARMS sysconfig Operation 


Purpose 
Copies the system parameter structure into a user-specified buffer. 


Description 
The SYS_GETPARMS sysconfig operation copies the system parameter var structure into 


a user—allocated buffer. This structure may be used for informational purposes alone or 
prior to setting specific system parameters. 


In order to set system parameters, the required fields in the var structure must be modified, 
and then the SYS_SETPARMS sysconfig operation can be called to change the system 
runtime operating parameters to the desired state. 


The parmp parameter on the sysconfig subroutine points to a buffer that is to contain all or 
part of the var structure defined in the sys/var.h header file. The fields in the var_hdr part 
of the var structure are used for parameter update control. 


The parmlen parameter on the system call should be set to the length of the var structure or 
to the number of bytes of the structure that is desired. The complete definition of the system 
parameters structure can be found in the sys/var.h header file. 


Return Values 


The SYS_GETPARMS sysconfig operation returns a value of —1 if an error occurs and the 
errno global variable is set to the following: 


EACCES The calling process does not have the required privilege. 


EFAULT The calling process does not have sufficient authority to access the data 
area described by the parmp and parmien parameters provided on the 
subroutine. This error is also returned if an I/O error occurred when 
accessing data in this area. 


Related Information 
The. sysconfig subroutine. 


The SYS_SETPARMS sysconfig operation. 


Programming in the Kernel Environment in Kernel Extensions and Device Support 
Programming Concepts. 
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SYS KLOAD sysconfig Operation 


Purpose 


Loads a kernel extension into the kernel. 


Description 


The SYS_KLOAD sysconfig function is used to load a kernel extension object file specified 
by a pathname into the kernel. A kernel! module ID for that instance of the module is 
returned. The SYS_KLOAD sysconfig operation loads a new copy of the object file into the 
kernel even though one or more copies of the specified object file may have already been 
loaded into the kernel. The returned module ID can then be used for any of these three 
functions: 


e Subsequent invocation of the module’s entry point (using the sysconfig SYS_CFGKMOD 
operation) 


e Invocation of a device driver’s ddconfig routine (using the sysconfig SYS_CFGDD 
operation) 


e Unloading the kernel module (using the sysconfig SYS_KULOAD operation). 


The parmp parameter on the sysconfig subroutine must point to a cfg_load structure, 
(defined in the sys/sysconfig.h header file), with the path field specifying the path name for 
a valid kernel object file. The parmlen parameter should be set to the size of the cfg_load 
structure. 


Note: A separate sysconfig operation exists, the SYS_SINGLELOAD operation, which 
also loads kernel extensions. This operation, however, only loads the requested 
object file if it has not already been loaded. 


Loader Symbol Binding Support 


The following information describes the symbol binding support provided when loading 
kernel object files. 


Importing Symbols 
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Symbols imported from the kernel name space are resolved with symbols that exist in the 
kernel name space at the time of the load. (Symbols are imported from the kernel name 
space by specifying the #!/unix character string as the first field in an import list at link—edit 
time.) 


Kernel modules can also import symbols from other kernel object files. These other kernel 


object files are loaded along with the specified object file if they are required to resolve the 
imported symbols. 


Loader Symbol! Binding Support, described with the sysconfig SYS_KLOAD operation, 
explains the symbol binding support provided when loading kernel object files. 


Finding Directory Locations For Unqualified File Names 


If the module header contains an unqualified base filename for the symbol (no / (slash) 
characters in the name), a libpath search string is used to find the location of the shared 
object file required to resolve imported symbols. This libpath search string can be taken from 
one of two places. If the libpath field in the cfg_load structure is not NULL, then it points to 
a character string specifying the libpath to be used. However, if the libpath field is NULL, 
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then the libpath is taken from the module header of the object file specified by the path field 
in the same (cfg_load) structure. 


The libpath specification found in object files loaded in order to resolve imported symbols is 
not used. 


The kernel loader service does not support deferred symbol resolution. The load of the 
kernel object file is terminated with an error if any imported symbols cannot be resolved. 


Exporting Symbols 


Any symbols exported by the specified kernel object file are added to the kernel name 
space. This makes these symbols available to other subsequently loaded kernel object files. 
Any symbols specified with the SYSCALL keyword in the export list at linkedit time are 
added to the system call table at load time. These symbols are then available to application 
programs as a system call. 


Kernel object files loaded on behalf of the specified kernel object file, in order to resolve 
imported symbols, do not have their exported symbols added to the kernel name space. 


These object files are considered private since they do not export symbols to the global 
kernel name space. For these types of object files, a new copy of the object file is loaded on 
each SYS_KLOAD operation of a kernel extension that imports symbols from the private 
object file. In order for a kernel extension to add its exported symbols to the kernel name 
space, it must be explicitly loaded with the SYS_KLOAD sysconfig operation before any 
other object files using the symbols are loaded. For kernel extensions of this type (those 
exporting symbols to the kernel name space), typically only one copy of the object file should 
ever be loaded. 


Return Values 


If the object file is loaded without error, the module ID is returned in the kmid variable within 
the cfg_load structure and the subroutine returns a 0. 


On error, the subroutine returns a —1 and the errno global variable is set to one of the 
following values: 


EACESS One of the following reasons applies: 
e The calling process does not have the required privilege. 
e An object module to be loaded is not an ordinary file. 


e The mode of the object module file denies read—only permission. 


EFAULT The calling process does not have sufficient authority to access the data 
area described by the parmp and parmlen parameters provided on the 
system call. This error is also returned if an I/O error occurred when 
accessing data in this area. 


ENOEXEC The program file has the appropriate access permission, but has an invalid 
XCOFF object file indication in its header. The sysconfig SYS_KLOAD 
operation only supports loading of XCOFF object files. This error is also 
returned if the loader is unable to resolve an imported symbol. 


EINVAL The program file has a valid XCOFF indicator in its header, but the header 
is damaged or is incorrect for the machine on which the file is to be run. 
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ENOMEM The load requires more kernel memory than is allowed by the 
system—imposed maximum. 


ETXTBSY The object file is currently open for writing by some process. 


Related Information 
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The sysconfig subroutine. 


The SYS_SINGLELOAD sysconfig operation, SYS_KULOAD sysconfig operation, 
SYS_CFGDD sysconfig operation, SYS_CFGKMOD sysconfig operation. 


The ddconfig device driver entry point. 


System Call Kernel Extension Overview in Kernel Extensions and Device Support 
Programming Concepts. 


Device Driver Kernel Extension Overview in Kernel Extensions and Device Support 
Programming Concepts. 


Virtual File System Introduction in Kernel Extensions and Device Support Programming 
Concepts. 


Device Configuration Subsystem: Programming Introduction in Kernel Extensions and 
Device Support Programming Concepts. 


Programming in the Kernel Environment in Kernel Extensions and Device Support 
Programming Concepts. 


Understanding Kernel Extension Binding in Kerne/ Extensions and Device Support 
Programming Concepts. 
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SYS _KULOAD sysconfig Operation 


Purpose 
Unloads a loaded kernel object file and any imported kernel object files that were loaded 
with it. 

Description 


The SYS_KULOAD sysconfig operation unloads a previously loaded kernel file and any 
imported kernel object files that were automatically loaded with it. It does this by 
decrementing the load and use counts of the specified object file and any object file having 
symbols imported by the specified object file. 


The parmp parameter on the sysconfig subroutine should point to a cfg_load structure, as 
described for the SYS_KLOAD operation. The kmid field should specify the kernel module 
ID that was returned when the object file was loaded by the sysconfig SYS_KLOAD or 
SYS_SINGLELOAD operation. The path and libpath fields are not used for this command 
and can be set to NULL. The parmlen parameter should be set to the size of the cfg_load 
structure. 


Upon successful completion, the specified object file (and any other object files containing 
symbols that the specified object file imports) will have their load and use counts 
decremented. If there are no users of any of the module’s exports and its load count is 0, 
then the object file is immediately unloaded. 


However, if there are users of this module, (that is, there are modules bound to this module’s 
exported symbols), the specified module is not unloaded. Instead, it is unloaded on some 
subsequent unload request, when its use and load counts have gone to zero. The specified 
module is not in fact unloaded until all current users have been unloaded. 


Note: Care must be taken to ensure that a routine has freed all of its system resources 
before being unloaded. For example, a device driver is typically prepared for 
unloading by using the sysconfig subroutines SYS_CFGDD operation and 
specifying termination. 


Loader Symbol! Binding Support, described with the sysconfig SYS_KLOAD operation, 
explains the symbol binding support provided when loading kernel object files. 


Return Values 


lf the unload operation is successful or the specified object file’s load count is successfully 
decremented, a value of 0 is returned. 


On error, the specified file and any imported files are not unloaded, nor are their load and 
use counts decremented. A value of —1 is returned and the errno global variable is set to 
one of the following: 


EACESS The calling process does not have the required privilege. 


EINVAL Invalid module !D or the specified module is no longer loaded or already has 
a load count of 0. 


EFAULT The calling process does not have sufficient authority to access the data 
area described by the parmp and parmlen parameters provided to the 
subroutine. This error is also returned if an I/O error occurred when 
accessing data in this area. 
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Related Information 
The sysconfig subroutine. 


The SYS_KLOAD sysconfig operation, SYS_SINGLELOAD sysconfig operation, 
SYS_CFGDD sysconfig operation. 
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SYS _QDVSW sysconfig Operation 


Purpose 
Checks the status of a device switch entry in the device switch table. 


Description 
The SYS_QDVSW sysconfig operation checks the status of a device switch entry in the 
device switch table. 


The parmp parameter on the sysconfig subroutine points to a qry_devsw structure defined 
in the sys/sysconfig.h header file. The parmien parameter on the subroutine should be set 
to the length of the qry_devsw structure. \ 


The qry_devsw field in the qry_devsw structure is modified to reflect the status of the 
device switch entry specified by the qry_devsw field. (The value in the devno field 
corresponds to the major portion of the device number.) The following flags can be returned 
in the status field: 


DSW_UNDEFINED 
The device switch entry is not defined if this flag has a value of 0 on return. 


DSW_DEFINED 
The device switch entry is defined. 


DSW_CREAD The device driver in this device switch entry provides a routine for character 
reads or raw input. This flag is set when the device driver provides a 
ddread entry point. 


DSW_CWRITE 


The device driver in this device switch entry provides a routine for character 
writes or raw Output. This flag is set when the device driver provides a 
ddwrite entry point. 


DSW_BLOCK The device switch entry is defined by a block device driver. This flag is set 
when the device driver provides a ddstrategy entry point. 


DSW_MPX The device switch entry is defined by a multiplexed device driver. This flag 
is set when the device driver provides a ddmpx entry point. 


DSW_SELECT 


The device driver in this device switch entry provides a routine for handling 
the select or poll subroutines. This flag is set when the device driver 
provides a ddselect entry point. 


DSW_DUMP The device driver defined by this device switch entry provides the capability 
to support one or more of its devices as targets for a kernel dump. This flag 
is set when the device driver has provided a dddump entry point. 


DSW_CONSOLE 
The device switch entry is defined by the console device driver. 
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DSW_TCPATH 
The device driver in this device switch entry supports devices that are 
considered to be in the Trusted Computing Path and provides support for 
the revoke subroutine and frevoke subroutine. This flag is set when the 
device driver provides a ddrevoke entry point. 


DSW_OPENED 
The device switch entry is defined and the device has outstanding opens. 
This flag is set when the device driver has at least one outstanding open. 


The DSW_UNDEFINED condition is indicated when the device switch entry has not been 


defined or has been defined and subsequently deleted. Multiple status flags may be set for 
other conditions of the device switch entry. 


Return Values 


If no error is detected, this operation returns with a value of 0. If an error is detected, the 


return value is set to a value of -1. The errno global variable is also set to one of these 
three values: 


EACESS The calling process does not have the required privilege. 
EINVAL Device number exceeds the maximum allowed by the kernel. 
EFAULT The calling process does not have sufficient authority to access the data 


area described by the parmp and parmien parameters provided on the 
system call. This error is also returned if an I/O error occurred when 
accessing data in this area. 


Related Information 
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The sysconfig subroutine. 


The ddread device driver entry point, ddwrite device driver entry point, ddstrategy device 
driver entry point, ddmpx device driver entry point, ddselect device driver entry point, 
dddump device driver entry point, ddrevoke device driver entry point. 


console special file. 


Understanding the Device Switch Table in Kerne/l Extensions and Device Support 
Programming Concepts. 


Trusted Computing Path Support In a Character Device Driver in Kernel Extensions and 
Device Support Programming Concepts. 


Understanding Block I/O Device Drivers in Kernel Extensions and Device Support 
Programming Concepts. 


Providing Raw !/O Support In a Block I/O Device Driver in Kernel Extensions and Device 
Support Programming Concepts. 


Understanding Character I/O Device Drivers, Multiplexed Support In a Character Device 
Driver in Kernel Extensions and Device Support Programming Concepts. 


System Call Kernel Extension Overview in Kernel Extensions and Device Support 
Programming Concepts. 


Device Driver Kernel Extension Overview in Kernel Extensions and Device Support 
Programming Concepts. 
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Virtual File System Introduction in Kernel Extensions and Device Support Programming 
Concepts. 


Device Configuration Subsystem: Programming Introduction in Kernel Extensions and 
Device Support Programming Concepts. 


Programming in the Kernel Environment in Kernel Extensions and Device Support 
Programming Concepts. 


Understanding Kernel Extension Binding in Kernel Extensions and Device Support 
Programming Concepts. 
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SYS QUERYLOAD sysconfig Operation 


Purpose 
Determines if a kernel object file has already been loaded. 


Description 
The SYS_QUERYLOAD sysconfig operation performs a query operation to determine if a 
given object file has been loaded. This object file is specified by the path field in the 
cfg_load structure passed in with the parmp parameter. This operation utilizes the same 
cfg_load structure that is specified for the SYS_KLOAD operation. 


If the specified object file is not loaded, the kmid field in the cfg_load structure is set to a 
value of 0 on return. Otherwise, the kernel module ID of the module is returned in the kmid 
field. If multiple instances of the module have been loaded into the kernel, the module !D of 
the one most recently loaded is returned. 


The libpath field in the cfg_load structure is not used for this option. 


Note: Note that a path name comparison is done to determine if the specified object file 
has been loaded. This operation will erroneously return a not loaded condition if the 
path name to the object file is expressed differently than it was on a previous load 
request. 


Loader Symbol Binding Support, described with the sysconfig SYS_KLOAD operation, 
explains the symbol binding support provided when loading kernel object files. 


Return Values 
If the specified object file is found, the module !D is returned in the kmid variable within the 
cfg_load structure and the subroutine returns a 0. If the specified file is not found, a kmid 
variable of 0 is returned with a return code of 0. On error, the subroutine returns a ~1 and the 
errno global variable is set to one of the following values: 


EACCES The calling process does not have the required privilege. 


EFAULT The calling process does not have sufficient authority to access the data 
area described by the parmp and parmlen parameters provided on the 
subroutine. This error is also returned if an I/O error occurred when 
accessing data in this area. 


EFAULT The path parameter points to a location outside of the process’s allocated 
address space. 


EIO - Anl/O error occurred during the operation. 


Related Information 
The sysconfig subroutine. 
The SYS_SINGLELOAD sysconfig operation, SYS_KLOAD sysconfig operation. 


Loader Symbol Binding Support in the SYS_KLOAD sysconfig operation. 
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Programming in the Kernel Environment in Kerne/ Extensions and Device Support 
Programming Concepts. 


Understanding Kernel! Extension Binding in Kernel Extensions and Device Support 
Programming Concepts. 
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SYS _SETPARMS sysconfig Operation 


Purpose 


Sets the kernel runtime tunable parameters. 


Description 


The SYS_SETPARMS sysconfig operation sets the current system parameters from a copy 
of the system parameter var structure provided by the caller. Only the runtime tunable 
parameters in the var structure can be set by this subroutine. 


lf the var_vers and var_gen values in the caller-provided structure do not match the 
var_vers and var_gen values in the current system var structure, no parameters are 
modified and an error is returned. The var_vers, var_gen and var_size fields in the 
structure should not be altered. The var_vers value is assigned by the kernel and is used to 
insure that the correct version of the structure is being used. The var_gen value is a 
generation number having a new value for each read of the structure. This provides 
consistency between the data read by the SYS_GETPARMS operation and the data written 
by the SYS_SETPARMS operation. 


The parmp parameter on the sysconfig subroutine points to a buffer that contains all or part 
of the var structure as defined in the <sys/var.h> header file. 


The parmlen parameter on the subroutine should be set either to the length of the var 
structure or to the size of the structure containing the parameters to be modified. The 
number of system parameters modified by this operation is determined either by the parmlen 
parameter value or by the var_size field in the caller-provided var structure. (The smaller of 
the two values is used.) 


The structure provided by the caller must contain at least the header fields of the var 
structure. Otherwise, an error will be returned. Partial modification of a parameter in the var 
structure can occur if the caller’s data area does not contain enough data to end on a field 
boundary. It is up to the caller to ensure that this does not happen. 


Return Values 
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The SYS_SETPARMS sysconfig operation returns a value of —1 if an error occurred, and 
the errno global variable is set to one of the following: 


EACESS The calling process does not have the required privilege. 
EINVAL One of the following error situations exists: 


e The var_vers version number of the provided structure does not match 
the version number of the current var structure. 


e The structure provided by the caller does not contain enough data to 
specify the header fields within the var structure. 


e One of the specified variable values is invalid or not allowed. On the 
return from the subroutine, the var_vers field in the caller-provided buffer 
contains the byte offset of the first variable in the structure that was 
detected in error. 
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EAGAIN The var_gen generation number in the structure provided does not match 
the current generation number in the kernel. This occurs if consistency is 
lost between reads and writes of this structure. The caller should repeat the 
read, modify, and write operations on the structure. 


EFAULT The calling process does not have sufficient authority to access the data 
area described by the parmp and parmien parameters provided to the 
subroutine. This error is also returned if an I/O error occurred when 
accessing data in this area. 


Related Information 
The sysconfig subroutine. 


The SYS_GETPARMS sysconfig operation. 


Understanding Kernel Extension Binding in Kernel Extensions and Device Support 
Programming Concepts. 
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SYS_SINGLELOAD sysconfig Operation 


Purpose 


Loads a kernel extension module if it is not already loaded. 


Description 


The SYS_SINGLELOAD sysconfig operation is identical to the SYS_KLOAD operation, 
except that the SYS_SINGLELOAD operation loads the object file only if an object file with 
the same path name has not already been loaded into the kernel. 


If an object file with the same path name has already been loaded, the module ID for that 
object file is returned in the kmid field and its load count incremented. If the object file is not 


loaded, this operation performs the load request exactly as defined for the SYS_KLOAD 
function. 


This option is useful in supporting global kernel routines where only one copy of the routine 


and its data can be present. Typically routines that export symbols to be added to the kernel 
name space are of this type. 


Note: Note that a path name comparison is done to determine if the same object file has 
already been loaded. This function will erroneously load a new copy of the object file 
into the kernel if the path name to the object file is expressed differently than it was 
on a previous load request. 


Loader Symbol Binding Support, described with the sysconfig SYS_KLOAD operation, 
explains the symbol binding support provided when loading kernel object files. 


Return Values 


The SYS_SINGLELOAD operation returns the same set of error codes that the 
SYS_KLOAD operation returns. 


Related Information 
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The sysconfig subroutine. 
The SYS_KLOAD sysconfig operation. 


Programming in the Kernel Environment in Kernel Extensions and Device Support 
Programming Concepts. 


Understanding Kernel Extension Binding in Kernel Extensions and Device Support 
Programming Concepts. 
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Appendix A. Base Operating System Error Codes for 
Services That Require Path Name Resolution 


The following errors apply to any service that requires path name resolution: 


EACCES 
EFAULT 


ELOOP 


ENAMETOOLONG 


ENOENT 


ENOENT 


ENOENT 
ENOTDIR 


ESTALE 


EIO 


Search permission is denied on a component of the path prefix. 


The Path parameter points outside of the allocated address 
space of the process. 


Too many symbolic links were encountered in translating the 
Path parameter. 


A component of a path name exceeded 255 characters and the 
process has the DisallowTruncation attribute (see the ulimit 
subroutine), or an entire path name exceeded 1023 characters. 


A component of the path prefix does not exist. 


A symbolic link was named, but the file to which it refers does not 
exist. 


The path name is null. 
A component of the path prefix is not a directory. 


The root or current directory of the process is located in a virtual 
file system that is unmounted. 


An I/O error occurred during the operation. 
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Appendix B. ODM Error Codes 


When an ODM subroutine fails, a value of —1 is returned and the odmerrno variable is set to 
one of the following values: 
ODMI_BAD_CLASSNAME 
The specified object class name does not match the object class name in 
the file. Check path name and permissions. 


ODMI_BAD_CLXNNAME 
The specified collection name does not match the collection name in the file. 


ODMI_BAD_CRIT 
The specified search criteria is incorrectly formed. Make sure the criteria 
contains only valid descriptor names and the search values are correct. For 
information on qualifying criteria, see Understanding ODM Object 
Searches in General Programming Concepts. 


ODMI_BAD_LOCK 
Cannot set a lock on the file. Check path name and permissions. 


ODMI_BAD_TIMEOUT 
The timeout value was not valid. It must be a positive integer. 


ODMI_BAD_TOKEN 
Cannot create or open the lock file. Check path name and permissions. 


ODMI_CLASS_DNE 


The specified object class does not exist. Check path name and 
permissions. 


ODMI_CLASS EXISTS 


The specified object class already exists. An object class must not exist 
when it is created. 


ODMI_CLASS_PERMS 
The object class cannot be opened because of the file permissions. 


ODMI_CLXNMAGICNO ERR 
The specified collection is not a valid object class collection. 


ODMI_FORK 
Cannot fork the child process. Make sure the child process is executable 
and try again. . 


ODMI_INTERNAL_ERR 


An internal consistency problem occurred. Make sure the object class is 
valid or contact the person responsible for the system. 


ODMI_INVALID_CLASS 
The specified file is not an object class. 
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ODMI_INVALID_CLXN 
Either the specified collection is not a valid object class collection or the 
collection does not contain consistent data. 

ODMI_INVALID_PATH 
The specified path does not exist on the file system. Make sure the path is 
accessible. 

ODMI_LINK_NOT_FOUND 
The object class that is linked to could not be opened. Make sure the linked 
object class is accessible. 

ODMI_LOCK_BLOCKED 
Cannot grant the lock. Another process already has the lock. 


ODMI_LOCK_ENV 
Cannot retrieve or set the lock environment variable. Remove some 
environment variables and try again. 
ODMI_LOCK_ID 
The lock identifier does not refer to a valid lock. The lock identifier must be 
the same as what was returned from the odm_lock subroutine. 
ODMI_MAGICNO_ERR 
The class symbol does not identify a valid object class. 


ODMI_MALLOC_ERR 


Cannot allocate sufficent storage. Try again later or contact the person 
responsible for the system. 


‘ODMI_NO_OBJECT 


The specified object identifier did not refer to a valid object. 


ODMI_OPEN_ERR 
Cannot open the object class. Check path name and permissions. 


ODMI_OPEN_PIPE 
Cannot open a pipe to a child process. Make sure the child process is 
executable and try again. 
ODMI_PARAMS 
The parameters passed to the subroutine were not correct. Make sure there 
are the correct number of parameters and that they are valid. 
ODMI_READ_ONLY 
The specified object class is opened as read-only and cannot be modified. 


ODMI_READ PIPE 


Cannot read from the pipe of the child. Make sure the child process is 
executable and try again. 


ODMI_TOOMANYCLASSES 


Too many object classes have been accessed. An application can only 
access less than 1024 object classes. 
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ODMI_UNLINKCLASS_ERR 


Cannot remove the object class from the file system. Check path name and 
permissions. 


ODMI_UNLINKCLXN_ERR 


Cannot remove the object class collection from the file system. Check path 
name and permissions. 


ODMI_UNLOCK 
Cannot unlock the lock file. Make sure the lock file exists. 
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Appendix C. List of X.25 API Error Codes 


List of X.25-Specific Error Codes 


For X.25-specific error conditions, x25_errno is set to one of the following values: 


X25ACKREQ 


X25AUTH 


X25AUTHCTR 


X25AUTHLISTEN 


X25BADCONNID 
X25BADDEVICE 
X25BADID 
X25BADLISTENID 
X25CALLED 


X25CALLING 


X25CTRUSE 
X25INIT 


X25INVCTR 


X25INVFAC 
X25INVMON 
X25LINKUP 
X25LINKUSE 


X25LONG 


One or more packets require acknowledgement. Issue x25_ack 
before continuing. 


The calling application does not have system permission to 
control the status of the link. 


The application does not have permission to remove this counter 
because it is not the application that issued the corresponding 
x25_ctr_get. 


The application cannot listen to this name, because the 
corresponding eniry in the routing list has a user name that 
excludes the user running the application. Use another routing 
list name, or change the user name in the routing list entry. 


The connection identifier is invalid. 

The X.25 port name is invalid. 

The connection identifier or listen identifier is invalid. 
The listen identifier is invalid. | 


The called address is invalid. Check that the address is correct 
and is a NULL-terminated string. 


The calling address is invalid. Check that the address is correct 
and is a NULL-terminated string. 


The counter has a non-zero value. - 


X.25 is already initialized for this X.25 port, so cannot be 
initialized again. 


The specified counter does not exist. (In the case of 
x25_ctr_wait, the counter is one of an array of counters.) 


An optional facility requested is invalid. Check cb_fac_struct. 
The monitoring mode is invalid. 
The X.25 port is already connected. 


The X.25 port still has virtual circuits established; it may still be in 
use. Either free all virtual circuits or disconnect the port using the 
override. 


The parameter is too long. Check each of the parameters for this 
subroutine. 
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X25MAXDEVICE 


X25MONITOR 


X25NAMEUSED 
X25NOACKREQ 
X25NOCARD 
X25NOCTRS 


X25NODATA 


X25NODEVICE 
X25NOLINK 


X25NONAME 


X25NOSUCHLINK 
X25NOTINIT 


X25NOTPVC 


X25PROTOCOL 


X25PVCUSED 


X25RESETCLEAR 


X25SYSERR 


X25TABLE 


X25TIMEOUT 


X25TOOMANYVCS 


Attempts have been made to connect more X.25 ports than are 
available. Check the smit configuration to see how many ports 
are available. 


X.25 traffic on this X.25 port is already being monitored by 
another application. The other application must stop monitoring 
before any other application can start it. 


Calls for this name are already being listened for. 

No packets currently require acknowledgement. 

The X.25 adapter is either not installed or not functioning. 
No counters are available. 


No data is has arrived for this connection identifier. Issue 
x25_ctr_wait to be notified when data arrives. 


The X.25 device driver is either not installed or not functioning. 


The X.25 port is not connected. Issue x25_link_connect, or use 
xmanage to connect it. 


The name is not in the routing list. Add the name or use one that 
is already in the list. 


The X.25 port does not exist. Check the smit configuration. 


The application has not initialized X.25 communications. Issue 
x25_init. 


This is not defined as a permanent virtual circuit (PVC). Check 
the smit configuration. 


An X.25 protocol error occurred. 


This permanent virtual circuit (PVC) is already allocated to 
another application. The other application must free the PVC 
before it can be used. 


The call was reset or cleared during processing. Issue 
x25_receive to obtain the reset-indication or clear-indication 
packet. Then issue x25_reset_confirm or x25_clear_confirm, 
as necessary. 


An error occurred that was not an X.25 error. Check the value of 
errno. 


The routing list cannot be updated because xroute is using it. Try 
again after xroute has completed. 


A timeout problem occurred. 


No virtual circuits are free on the listed X.25 ports. 
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X25TRUNCTX The packet size is too big for internal buffers, so data cannot be 
sent. 


List of System Error Codes 
For non-X.25-specific error conditions, x25_errno is set to X25SYSERR and errno is set to 
one of the following values: 


EFAULT Bad address pointer. 

EINTR A signal was caught during the call. 

EIO An \/O error occurred. 

ENOMEM Could not allocate memory for device information. 
ENOSPC There are no buffers available in the pool. 

EPERM Calling application does not have sufficient authorization. 
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Special Characters 


_atojis macro, 1-285 

_exit subroutine, 1-127—1-128 
_jistoa macro, 1-285 

_NLxout subroutine, 1-484 
_tojlower macro, 1-285 
_tojupper macro, 1-285 


A 


a64i subroutine, 1-3 
abort subroutine, 1-4 
abs subroutine, 1-5—1-6 
absinterval subroutine, 1-190—1-—-192 
accept a connection on a socket, Sockets, 8-3 
accept subroutine, Sockets, 8-3 
access control information 
changing 
using acl_chg subroutine, 1-11—1-13, 
1—706—1-708 
using acl_fchg subroutine, 1-11—1-13 
getting, using acl_get subroutine, 1-14—1-15 
setting 
using acl_fset subroutine, 1-19—1-21 
using acl_set subroutine, 1-19—1-—21 
access data stored under a key, fetch, 5-44 
access data stored under key, dom_fetch, 5-36 
access subroutine, 1-7—1-8 
acct subroutine, 1-9—1-10 
acl_chg subroutine, 1-11—1—-13 
acl_fchg subroutine, 1-11—1-13 
acl_get subroutine, 1-14—1—15 
acl_put subroutine, 1-16—1-18 
acl_set subroutine, 1-19—1-21 
acos subroutine, 1-673—1-674 
acosh subroutine, 1-26 
add group or multicast receive address, DLC, 3-57 
addresses, define program, 1-117 
addssys subroutine, 1-22—1-—23 
adjtime subroutine, 1-24—1-25 
advance subroutine, 1-87—1-90 
AIX API application, HCON programming 
receiving message from, 2-62 
sending message to, 2-78 
starting interaction with, 2-15 
AIX Input Method, notifying input auxiliary area, 
using IMProcess Auxiliary subroutine, 
1-271—1-272 
aix_exec function, xgmon, 6-3 
alarm subroutine, 1-190—1-—192 
alloc function, xgmon, 6—4 
alloca subroutine, 1-399—1-—402 


allow command execution on a remote host, 
Sockets, 8-98 . 
allow execution of commands on a remote host, 
Sockets, 8-82 
allow servers to authenticate clients, Sockets, 8-102 
allow VGM to change current display element mask, 
xgmon, 6-71 
allow VGM to issue system command, xgmon, 6-16 
allow VGM to start execution of library command in 
other VGM, xgmon, 6-16 
alphasort subroutine, 1-591—1-592 
alter a link station’s configuration parameters, DLC, 
3-42 
alter normally defaulted parameters, DLC, 3-61 
API for X.25 
initializing, using x25_init subroutine, 9-19 
terminating for a specified X.25 port, using 
x25_term subroutine, 9-38 . 
array, allocating space, using imcalloc subroutine, 
1-256 
ascii function, xgmon, 6-5 
asctime subroutine, 1-101—1-—103 
asin subroutine, 1-673—1-674 
asinh subroutine, 1-26 
assert macro, 1-27 
asynchronous event call, DLC, 3-64 
atan subroutine, 1-673—1-674 
atan2 subroutine, 1-673—1-674 
atanh subroutine, 1-26 
atexit subroutine, 1-127—1-128 
atof subroutine, 1-28—1-29 
atoff subroutine, 1-28—1-29 
atoi subroutine, 1-721—1-—722 
atojis subroutine, 1-285 
atol subroutine, 1-721—1-—722 
attach to session with extended open capabilities, 
HCON programming, 2-55 
attach to session, HCON programming, 2-49 
audit 
generating an audit record, using auditlog 
subroutine, 1-37—1-38 
reading a record, using auditread subroutine, 
1-47 
writing a record, using auditwrite subroutine, 
1-48 
audit bins, compressing and uncompressing, using 
auditpack subroutine, 1-42—1-—43 
audit subroutine, 1-30—1-31 
auditbin subroutine, 1-32—1-—34 
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auditevents subroutine, 1-35—1-36 
auditing 
defining a file, using auditbin subroutine, 
1-32—1-34 
disabling, using audit subroutine, 1-30—1-31 
enabling, using audit subroutine, 1-30—1-31 
getting system event status, using auditevents 
subroutine, 1-35—1-36 
setting mode of system data object, using 
auditobject subroutine, 1-39—1-41 
setting system event status, using auditevents 
subroutine, 1-35—1-36 
- auditlog subroutine, 1-37—1-38 
auditobj subroutine, , 1-40 
auditobject subroutine, 1-39—1-41 
auditpack subroutine, 1-42—1-43 
auditproc subroutine, 1-44—1—46 
auditread subroutine, 1-47 
auditwrite subroutine, 1-48 
auth_destroy macro, RPC, 5-6 
authdes_create subroutine, RPC, 5-3 
authdes_getucred subroutine, RPC, 5-5 
authentication 
closing the database, using endpwdb 
subroutine, 1-631—1-632 
opening the database, using setpwdb 
subroutine, 1-631—1-632 
authnone_create subroutine, RPC, 5-7 
authunix_create subroutine, RPC, 5-8 
authunix_create_default subroutine, RPC, 5-9 
auxiliary area, hiding, using IMAuxHide subroutine, 
1-254 


B 


base_type function, xgmon, 6-6 

Baud Rates Subroutines 
cfgetispeed subroutine, 1-61—1-62 
cfgetospeed subroutine, 1-61—1-62 
cfsetispeed subroutine, 1-61—1-62 
cfsetospeed subroutine, 1-61—1-62 

bemp subroutine, 1-49 

bcopy subroutine, 1-49 

begin LAF script, HCON programming, 2-94 

Berkeley Compatibility Library 
alloca subroutine, 1-399—1-402 
calloc subroutine, 1-399—1-—402 
fmin subroutine, 1-396—1-398 
fmout subroutine, 1-396—1-398 
free subroutine, 1-399—1-—402 
ftime subroutine, 1-218—1-219 
gcd subroutine, 1-396—1-398 
invert subroutine, 1-396—1-398 
itom subroutine, 1~396—1-398 
m_in subroutine, 1-396—1-398 
m_out subroutine, 1-396—1-398 
madd subroutine, 1-396—1-398 
mallinfo subroutine, 1-399—1-—402 
malloc subroutine, 1-399—1-—402 
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mallopt subroutine, 1-399—1—402 
mcmp subroutine, 1-396—1-398 
mdiv subroutine, 1-396—1-—398 
min subroutine, 1-396—1-398 
mkstemp subroutine, 1-421 
mout subroutine, 1-396—1-398 
move subroutine, 1-396—1-398 
msaqrt subroutine, 1-396—1-398 
msub subroutine, 1-396—1-—398 
mult subroutine, 1-396—1-—398 
nice subroutine, 1-204—1-205 
nlist subroutine, 1-469—1—470 
omin subroutine, 1~396—1-398 
omout subroutine, 1-396—1-398 
pow subroutine, 1-396—1-398 
psignal subroutine, 1-548 
rand subroutine, 1-564—1—565 
re_comp subroutine, 1-568 
re_exec subroutine, 1-568 
realloc subroutine, 1-399—1-—402 
rpow subroutine, 1-396—1-398 
sdiv subroutine, 1-396—1-—398 
signal subroutine, 1-651 
sigvec subroutine, 1-651 
srand subroutine, 1-564—1-—565 
sys_siglist vector, 1-548 
vfork subroutine, 1-147 
vtimes subroutine, 1-211—1-213 
bind a name to a socket, Sockets, 8-5 
bind subroutine, Sockets, 8-5 
binding handles 
clearing, 4-29 
clearing server bindings, 4-30 
freeing, 4-32 
socket address representation, 4-33 
BREAK LAF statement, HCON programming, 2-3 
brk subroutine, 1-52—1-53 
bsearch subroutine, 1-54 
bytes, copy, using swab subroutine, 1-724 
bzero subroutine, 1—49 


C 


cabs subroutine, 1-248—1-249 
call for X.25 
accepting an incoming, using x25_call_accept 
subroutine, 9-6 
clearing, using x25_call_clear subroutine, 
9-7—9-8 
making, using x25_call subroutine, 9-4—9-—5 
starting listening for incoming, using x25_listen 
subroutine, 9-30 
turning off listening for, using x25_deafen 
subroutine, 9-16 
calling process 
returning parent process group ID, using 
getppid subroutine, 1-202 
returning process ID, using getpid subroutine, 
1-202 


returning the process group ID, using getpgrp 
subroutine, 1-202 
suspending, using pause subroutine, 1-527 
calloc subroutine, 1-399—1~—402 
callroc subroutine, RPC, 5-10 
catclose subroutine, 1-56 
catgetmsg subroutine, 1-57 
catgets subroutine, 1-58 
catopen subroutine, 1-59—1-—-60 
cbrt subroutine, 1-676 
ceil subroutine, 1-141—1-143 
cfxfer function, HCON programming, 2—4 
chacl subroutine, 1-63—1-65 
change configuration parameters, DLC, 3-22, 3~28 
change current primary address of host, xgmon, 
6-54 
change NIS map, yp_update, 5-144 
change relative location of display element, xgmon, 
6-52 
change remote address/name result extension, DLC, 
3-56 
character 
classifying 
using ctype subroutines, 1-104—1-105 
using Japanese ctype subroutines, 
1-287— 1-291 
using NCctype subroutines, 1-453—1—455 
determining the length of multipbyte character, 
using mblen subroutine, 1-405 
locating first occurence in a string, using 
wcspbrk subroutine, 1-803 
translating 
Japanese conv subroutine, 1-285—1-—286 
using conv subroutines, 1-91—1-93 
character data 
read and interpret according to a format, using 
wsscanf subroutine, 1-815 
read and interpret according to format, 
1-593—1-597 
chdir subroutine, 1-66—1-67 
check file descriptor readiness, DLC, 3-73 
check I/O status, file descriptors and message 
queues, using select subroutine, 1-598—1-—600 
check the status of the programmatic file transfer, 
HCON programming, 2-4 
chmod subroutine, 1-68—1-—70 
chown subroutine, 1-71—1-73 
chownx subroutine, 1-71—1-73 
chroot subroutine, 1-74—1-—75 
chssys subroutine, 1-76—1-77 
Cjistosj subroutine, 1-292—1-—293 
ckuseracct subroutine, 1-80—1-—81 
ckuserlD subroutine, 1-78—1~—79 
class subroutine, 1-82—1-83 
clearerr macro, 1-140 
cint_broadcast subroutine, RPC, 5-12 
cilnt_call macro, RPC, 5-14 
clnt_control macro, RPC, 5-16 
clnt_create subroutine, RPC, 5-18 


cint_destroy macro, RPC, 5-19 
cint_freeres macro, RPC, 5-20 
clnt_geterr macro, RPC, 5-21 
clnt_pcreateerror subroutine, RPC, 5—22 
clnt_perrno subroutine, RPC, 5-23 
clnt_perror subroutine, RPC, 5-24 
clnt_spcreateerror subroutine, RPC, 5-25 
clnt_sperrno subroutine, RPC, 5-26 
cilnt_sperror subroutine, RPC, 5-28 
cintraw_create subroutine, RPC, 5-29 
clnttcp_create subroutine, RPC, 5-30 
clntudp_create subroutine, RPC, 5—32 
clock, system, correcting time for synchronization, 

using adjtime subroutine, 1-24—1-25 
clock subroutine, 1-84 
close a file, 1-85—1-—86 
close function, xgmon, 6-7 
close open file, xgmon, 6-7 
close subroutine, 1-85—1-—86 

DLC, 3-3 

close subroutine for generic SNA, SNA, 7-5 
close subroutine for SNA Services/6000, SNA, 7-3 
close the /etc/service file entry, Sockets, 8-22 
closedir subroutine, 1-522—1-524 


closelog subroutine, 1-734 


closes a database, dbmclose, 5-41 
closes the /etc/protocols file, Sockets, 8-21 
closes the database, dbm_close, 5-34 
closes the networks file, Sockets, 8-20 
code points, returning the number, using NCcplen 
suboutine, 1-465 
compare and swap data, 1-98—-1—99 
compile and match patterns, 1-578 
compile subroutine, 1-87—1-—90 
compress a domain name, Sockets, 8-11 
connect subroutine, Sockets, 8-8 
connect two sockets, Sockets, 8-8 
contact a remote station for a link station, DLC, 3-41 
control garbage collection by VGM, xgmon, 6-63 
control open file descriptors, 1-336—1-—338 
control operations, using IMloctl subroutine, 
1-—266—1-—267 . 
controlling terminal, generate path name for, using 
ctermid subroutine, 1-100 
conversion 
date and time to string representation 
using asctime subroutine, 1-101—1-103 
using ctime subroutine, 1-101—1-103 
using difftime subroutine, 1-101—1-103 
using gmtime subroutine, 1-101—1-103 
using localtime subroutine, 1-101—1-—103 
using mktime subroutine, 1-101—1-—103 
using strftime subroutine, 1-101—1—-103 
using timezone subroutine, 1-101—1-103 
using tzset subroutine, 1-101—1-103 
multibyte character string to wide—character 
string, using mbstowcs subroutine, 1-413 
multipbyte character to wide character, using 
mbtowc subroutine, 1-414 
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wide—character sequence to multibyte 
character sequence, 1-806 
wide—character to multibyte character, wctomb 
subroutine, 1-808 
convert an Internet address to ASCII, Sockets, 8-72 
convert Internet addresses to Internet numbers, 
Sockets, 8-62 
convert Internet dot notation addresses to Internet 
numbers, Sockets, 8-70 
convert long integer from host order to Internet order, 
Sockets, 8-60 
convert long integer from network byte order to host 
byte order, Sockets, 8-76 
convert short integer from host order to Internet 
order, Sockets, 8-61 
convert short integer from network byte order to host 
byte order, Sockets, 8-77 
converting character strings to UUIDs, 4—47 
converting host names to socket addresses, 4—36 
converting UUIDs to character strings, 4—48 
copysign subroutine, 1-94—1-95 
cos subroutine, 1-673—1-674 
cosh subroutine, 1-675 
counter for X.25 
getting a, using x25_ctr_get subroutine, 9-11 
removing, using x25_ctr_remove subroutine, 
9-12 
returning the current value of, using 
x25_ctr_test subroutine, 9-13 
waiting for changes in value, using 
x25_ctr_wait subroutine, 9-14—9-15 
creat subroutine, 1-517 
create a pair of connected sockets, Sockets, 8-129 
create a socket and return a descriptor, Sockets, 
8-126 
create link between hosts, xgmon, 6-48 
create node or host, xgmon, 6—47 
create UDP socket to communicate with SNMP 
agent, SNMP, 6-8 
create_SNMP_port subroutine, 6-8 
crypt subroutine, 1-96—1-97 
cs subroutine, 1-98—1-99 
csjtojis subroutine, 1-292—1-293 
csjtouj Subroutine, 1-292—1-293 
> ctermid subroutine, 1-100 
ctime function, xgmon, 6-9 
ctime subroutine, 1-101—1-103 
cujtojis subroutine, 1—-292—1-—293 
Cujtos} Subroutine, 1-292—1-293 
cuserid subroutine, 1-106 


D 


data packet for X.25 
acknowledging with the D-bit set, using 
x25_ack subroutine, 9-3 
sending a, using x25_send subroutine, 9-37 
datagram data received routine, DLC, 3-63 
datagram packet received call, DLC, 3-63 
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date 
formatting, using NLstrtime subroutine, 
1-—475—1-477 
getting, using gettimeofday subroutine, 
1-218—1-219 
setting, using settimeofday subroutine, 
1-218—1-219 
DBM 
dbmclose subroutine, 5-41 
dbminit subroutine, 5-42 
delete subroutine, 5—43 
fetch subroutine, 5-44 
firstkey subroutine, 5—45 
nextkey subroutine, 5—55 
store subroutine, 5-65 
dbm_close subroutine, 5-34 
dbm_delete subroutine, 5-35 
dbm_fetch subroutine, 5-36 
dbm_first subroutine, 5-37 
dbm_nextkey subroutine, 5-38 
dbm_open subroutine, 5-39 
dbm_store subroutine, 5-40 
dbmclose subroutine, 5—41 
dbminit subroutine, 5—42 
debug LAF script, HCON programming 
disabling, 2-86 
enabling messages, 2-7 
DEBUG LAF statement, HCON programming, 2-7 
decode device handler name, DLC, 3-10 
decode SNMP packet, SNMP, 6-56 
decode special functions commands, DLC, 3-8 
default domain of NIS node, 5-137 
defssys subroutine, 1~107—1-108 
delete key and associated contents, dbm_delete, 
9-35 
delete key and associated contents, delete, 5-43 
delete subroutine, 5-43 
delssys subroutine, 1-109 
dep_info function, xgmon, 6—10 
descriptor table, getting the size, 1-177 
detach AIX API from session, HCON programming, 
2-21 | 
dfftime subroutine, 1-101—1-103 
directory 
changing, using chdir subroutine, 1-66—1-67 
creating, using mkdir subroutine, 
1—417—1-418 
gets path name, using getwd subroutine, 1-243 
gets the path name, using getcwd subroutine, 
1-176 
perform operations on directories, 
1-522—1-524 
removing an entry, using unlink subroutine, 
1~781—1-782 
renaming, using rename subroutine, 
1-584— 1-586 
disable a GDLC channel, 3-4, 3-21 
disable a GDLC channel,, 3-3 


disable a service access point, DLC, 3-35 
disable debugging in LAF script, HCON 
programming, 2-86 
disclaim subroutine, 1-110 
dispatching remote procedure calls, 4-35 
div subroutine, 1-5—1-6 
DLC entry points 
dicclose, 3-4 
dicconfig, 3-6 
dicioctl, 3-8 
dicmpx, 3-10 
dicopen, 3-12 
dicread, 3-14 
dicselect, 3-16 
dicwrite, 3-18 
DLC ioctl operations, 3-30 
dic_add_grp, 3-57 
dic_alter, 3-42 
dic_contact, 3-41 
dic_disable_sap, 3-35 
dic_enable_sap, 3-32 
dic_enter_lbusy, 3-50 
dic_enter_shold, 3-51 
dic_exit_lbusy, 3-50 
dic_exit_shold, 3-52 
dic_get_excep, 3-52 
dic_halt_ls, 3-39 
dic_query_Is, 3-48 
dic_query_sap, 3-47 
dic_start_Is, 3-36 
dic_test, 3-41 
dic_trace, 3-40 
iocinfo, 3-57 
DLC kernel services 
fp_close, 3-21 
fp_ioctl, 3-22 
fp_open, 3-24 
fp_write, 3-26 
DLC result extensions 
dic_radd_res — remote address/name change, 
3-56 
dic_sape_res — sap enabled, 3-55 
dic_stah_res — link station halted, 3-56 
dic_stas_res — link station started, 3-55 
DLC routines 
datagram data received, 3-63 
exception condition, 3-64 
|-frame data received, 3-65 
network data received, 3-66 
xid data received, 3-67 
DLC subroutines 
close, 3-3 
ioctl, 3-28 
open, 3-59 
extended parameters for, 3-61 
read, extended parameters for, 3-68 
readx, 3-71 
select, 3-73 
write, extended parameters for, 3-75 


writex, 3-77 
dic_add_grp ioctl operation, 3-57 
dic_alter ioctl operation, 3-42 
dic_contact ioctl operation, 3-41 
dic_disable_sap ioctl operation, 3-35 
dic_enable_sap ioctl operation, 3-32 
dic. enter_lbusy ioctl operation, 3-50 
dic_enter_shold ioct! operation, 3-51 
dic_exit_lbusy ioctl operation, 3-50 
dic_exit_shold ioctl operation, 3—52 
dic_get_excep ioctl operation, 3-52 
dic_halt_ls ioctl operation, 3-39 
dic_query_lIs ioctl operation, 3-48 
dic_query_sap ioctl operation, 3-47 
dic_start_ls ioctl operation, 3-36 
dic_test ioctl operation, 3-41 
dic_trace ioctl operation, 3-40 
dicclose entry point, 3-4 
dicconfig entry point, 3-6 
dicioctl entry point, 3-8 
dicmpx entry point, 3-10 
dicopen entry point, 3-12 
dicread entry point, 3-14 
dicselect entry point, 3-16 
dicwrite entry point, 3-18 
dn_comp subroutine, Sockets, 8-11 
dn_expand subroutine, Sockets, 8-13 
dn_find subroutine, Sockets, 8-15 
dn_skipname subroutine, Sockets, 8-17 
DO-END LAF statement, HCON programming, 2-8 
dotaddr function, xgmon, 6-12 
drand 48 subroutine, 1-111—1-113 
draw a line, xgmon, 6-13 
draw_line function, xgmon, 6-13 
draw_string function, xgmon, 6-14 
drem subroutine, 1-114 
dup subroutine, 1-135—1-139 
dup2 subroutine, 1-135—1-139 


E 


ecvt subroutine, 1-115—1-116 

edata identifier, 1-117 

enable a service access point, DLC, 3-32 

enable debugging messages in LAF script, HCON 
programming, 2-7 

enable display of formatted output in color, xgmon, 
6-14 

enable formatted arguments, xgmon, 6-77 

encode SNMP request, SNMP, 6—49 

encrypt subroutine, 1-96— 1-97 

end identifier, 1-117 

end interaction with a host application, HCON 
programming, 2-24 

end LAF script, HCON programming, 2-10 

end retrieval of network host entries, Sockets, 8-19 

end—of-file character, inquire about, using feof 
macro, 1-140 

endfsent subroutine, 1-179 
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endgrent subroutine, 1~182—1-183 
endhostent subroutine, Sockets, 8-19 
endnetent subroutine, Sockets, 8~20 
endprotoent subroutine, Sockets, 8-21 
endpwdb subroutine, 1-631—1-632 
endpwent subroutine, 1-206—1-207 
endservent subroutine, Sockets, 8-22 
endttyent subroutine, 1-224—1-—225 
endutent subroutine, 1-237—1-239 
endvfsent subroutine, 1-240—1-241 
enter local busy mode on a link station, DLC, 3-50 
enter short hold mode on a link station, DLC, 3-51 
enuserdb subroutine, 1~638—1—-639 
erand48 subroutine, 1-111—1-113 
erf subroutine, 1-118 
erfc subroutine, 1-118 
errlog subroutine, 1-119 
error codes, base operating system, for services 
requiring path name resolution, A-1 
error codes for X.25, non—X.25 specific, list of, C-3 
error handling 
controlling the system error log, 1-734 
including error messages, 1-27 
numbering an error message string, 1-715 
writing error messages, 1-529 
error information from load or exec subroutines, 
1-331—1-332 
errors, writing to the error log device driver, using 
errlog subroutine, 1-119 
etext identifier, 1-117 
exception condition routine, DLC, 3-64 
exchange identification packet received call, DLC, 
3-67 
exec function, xgmon, 6-16 
execl subroutine, 1-120—1-126 
execle subroutine, 1-120—1-—126 
execip subroutine, 1-120—1-126 
execute AIX programs and commands from within 
VGM, xgmon, 6-3 
execute LAF script subject statement, HCON 
programming, 2-97 
execute subject statment until tested condition is 
true, HCON programming, 2-90 
execution profiling 
start and stop after monitor initialization, 
1-—425—1-426 
start and stop using data areas defined in 
parameters, 1-427—1-435 
start and stop using default sized data areas, 
1-436— 1-439 
execv Subroutine, 1—-120-—1-—126 
execve subroutine, 1-120—1-126 
execvp subroutine, 1-120—1-126 
EXIT LAF statement, HCON programming, 2-9 
exit local busy mode on a link station, DLC, 3-50 
exit short hold mode on a link station, DLC, 3-52 
exit subroutine, 1-127—1-128 
exp subroutine, 1-129—1-131 
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expands a compressed domain name, Sockets, 
8-13 


~ expm1 subroutine, 1-129—1-131 


extract a substring at left, xgmon, 6—41 

extract a substring at right, xgmon, 6-64 

extract a substring from within string, xgmon, 6-51 

extract value of specified MIB instance ID for host, 
xgmon, 6-34 

extract variable name portion of instance ID, SNMP, 
6-17 

extract_SNMP_name subroutine, 6-17 
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fabs subroutine, 1-141—1-143 
fchmod subroutine, 1-68—1—70 
fchown subroutine, 1-71—1—73 
fchownx subroutine, 1—-71—1-73 
fclacl subroutine, 1-65 
fclear subroutine, 1—-132—1-133 
fclose subroutine, 1-134 
fent! subroutine, 1-135—1-139 
fevt subroutine, 1-115—1-116 
fdopen subroutine, 1-144—1-146 
feof macro, 1-140 
ferror macro, 1-140 
fetch subroutine, 5—44 
fflush subroutine, 1-134 
ffs subroutine, 1-49 
ffullstat subroutine, 1-711—1-—714 
fgetc subroutine, 1-174—1-175 
fgetpos subroutine, 1-167—1—168 
fgets subroutine, 1-214 
fgetwc subroutine, 1-242 
fgetws subroutine, 1-244—1-245 
file 
accessing utmp file entries, 1-237—1-239 
changing access permissions 
using chmod subroutine, 1-68—1-—70 
using fchmod subroutine, 1-68—1-—70 
changing the access control 
using acl_chg subroutine, 1-11—1-13 
using acl_fchg subroutine, 1-11—1-13 
changing the protection, using chacl 
subroutine, 1-63—1-65 
constructing a unique name, 1-421 
creating file or directory, using mknod, mkfifo 
subroutines, 1-419—1-—420 
creating temporary, using tmpfile subroutine, 
1-753 
determining accessibility, using access 
subroutine, 1-7—1-8. 
get vfs file entry, 1-240—1-241 
making a hole in, 1-132—1-133 
making a symbolic link, using symlink 
subroutine, 1-728—1-—730 
moving read/write pointer, using Iseek 
subroutine, 1-341—-1-342 


open for reading or writing, 1-517—1-521 
perform controlling operations, 1—135—1-139 
reading, 1-570—1-573 
removing, using remove subroutine, 1-583 
renaming, using rename subroutine, 
1-584— 1-586 
retrieving access control information, using 
acl_chg subroutine, 1-706—1-—708 
retrieving implementation characteristics, 
1-525—1-526 
revoking access, using revoke subroutine, 
1-587—1-588 
set and get value of file creation mask, using 
umask subroutine, 1-774 
setting access control information, using 
acl_put subroutine, 1-16—1-18 
setting the access control information 
using acl_fset subroutine, 1-19—1-21 
using acl_set subroutine, 1-19—1-21 
writing changes to permanent storage, using 
fsync subroutine, 1-169 
writing to, 1-809—1-812 
file descriptors, checking I/O status, using poll 
subroutine, 1-535—1-536 
file ownership, changing 
using chown subroutine, 1-71—1-73 
using chownx subroutine, 1-71—1-73 
using fchown subroutine, 1—-71—1-73 
using fchownx subroutine, 1-71—1-73 
file pointer, repositioning, using fseek subroutine, 
1-167—1-168 
file system 
getting information about, 1-179 
make file system available, 1-790 
file transfer, HCON programming 
initiating within program executing in AIX, 2-11 
invoking API, 2-29 
fileno macro, 1-140 
find set of all MIB variable names containing prefix, 
xgmon, 6-25 
find set of variable names containing prefix, SNMP, 
6-44 
FINISH LAF statement, HCON programming, 2-10 
finite subroutine, 1-82—1-83 
firstkey Subroutine, 5—45 
flag letters, get from an argument vector, 
1-194—1-195 
flock subroutine, 1-336 
floor subroutine, 1-141—1-—143 
flush the current trap, xgmon, 6-18 
flush_trap function, xgmon, 6-18 
fmin subroutine, 1-396 
fmod subroutine, 1-141—1-143 
fmout subroutine, 1-396 
font_height function, xgmon, 6-19 
font_width function, xgmon, 6-20 
fopen function, xgmon, 6-21 
fopen subroutine, 1-144—1-146 
fork subroutine, 1-147—1-149 


fp_any_enable subroutine, 1-150—1-151 
fp_any_xcp subroutine, 1-155 

fp_close kernel service, DLC, 3-21 
fp_cir_flag subroutine, 1-152—1-154 
fp_disable subroutine, 1-150 
fp_disable_all subroutine, 1-150 
fp_divbyzero subroutine, 1-155—1-156 
fp_enable subroutine, 1-150—1-151 
fp_enable_all subroutine, 1-150—1-—151 
fp_inexact subroutine, 1-155 
fp_invalid_op subroutine, 1-155—1-—156 
fp_ioct! kernel service, DLC, 3-22 
fp_iop_infdinf subroutine, 1-155 
fp_iop_infmzr subroutine, 1-155 
fp_iop_infsinf subroutine, 1-155 
fp_iop_invcmp subroutine, 1-155 
fp_iop_snan subroutine, 1-155 
fp_iop_zrdzr subroutine, 1-155 
fp_is_enabled subroutine, 1-150—1—151 
fp_open kernel service, DLC, 3-24 
fp_overflow subroutine, 1-155 
fp_read_flag subroutine, 1-152—1-154 
fp_read_rnd subroutine, 1-157—1-158 
fp_set_flag subroutine, 1-152—1-154 
fp_swap_flag subroutine, 1-152—1-—154 
fp_swap_rnd subroutine, 1-157—1-—158 
fp_underflow subroutine, 1-155 

fp_write kernel service, DLC, 3-26 
fpathconf subroutine, 1-525—1-526 
fprintf subroutine, 1-538—1-—543 

fputc subroutine, 1-555—1-556 

fputs subroutine, 1-558 

fputwc subroutine, 1-559—1—560 
fputws subroutine, 1—561 

fread subroutine, 1-159—1-160 
freopen subroutine, 1-144—1-—146 
frevoke subroutine, 1-161—1-162 
frexp subroutine, 1-163—1-164 

fscanf subroutine, 1-593—1-—597 

fseek subroutine, 1-167—1-—168 
fsetpos subroutine, 1-167—1-168 
fsstatfs system cll, 1-709—1-—710 

fstat subroutine, 1-711—1-714 

fstatac!l subroutine, 1-706—1-—708 
fstatx subroutine, 1-711—1-714 

fsync subroutine, 1-169 

ftell subroutine, 1-167—1-168 

ftime subroutine, 1-218—1-—219 

ftok subroutine, 1—-170—1-171 

ftruncate subroutine, 1-764—1—765 

ftw subroutine, 1-172 

fullstat subroutine, 1-711—1-—-714 

fwrite subroutine, 1-159—1—160 

fxfer function, HCON programming, 2-11 
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g32_alloc function, HCON programming, 2-17 
g32_close function, HCON programming, 2-21 
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g32_dealloc function, HCON programming, 2-24 

g32_fxfer function, HCON programming, 2-29 

g32_get_cursor function, HCON programming, 2-37 

g32_get_data function, HCON programming, 2-40 

g32_get_status function, HCON programming, 2-43 

g32_notify function, HCON programming, 2-46 

g32_open function, HCON programming, 2-49 

g32_openx function, HCON programming, 2-55 

g32_read function, HCON programming, 2-65 

g32_search function, HCON programming, 2-69 

g32_send_keys function, HCON programming, 2-74 

g32_write function, HCON programming, 2-80 

G32ALLOC function, HCON programming, 2-15 

G32DLLOC function, HCON programming, 2-27 

G32WRITE function, HCON programming, 2-78 

gamma subroutine, 1—322—1-323 

gcd subroutine, 1-396 

gevt subroutine, 1-115—1-116 

GDLC ioctl command opertions, 3-30 

generate text string corresponding to integer 
expression of time, xgmon, 6-9 

genprof command, HCON programming, 2-62 

get a protocol entry by name, Sockets, 8-40 

get a protocol entry by number, Sockets, 8-42 

get a protocol entry, Sockets, 8-44 

get default domain of node, yp_get_default_domain, 
5-137 

get file system statistics, 1-709—1-—710 

get network entry by address, Sockets, 8-33 

get network entry by name, Sockets, 8-35 

get network entry, Sockets, 8-37 

get network host entry by name, Socekts, 8-26 

get network hsot entry by address, Sockets, 8-24 

get options on sockets, Sockets, 8-56 

get service entry by name, Sockets, 8—46 

get service entry by port, Sockets, 8-48 

get service file entry, Sockets, 8-50, 8-119 

get socket name, Sockets, 8-54 

get the name of the current domain, Sockets, 8-23 

get the name of the peer socket, Sockets, 8-38 

get tty description file entry, 1-224 

get unique identifies of current host, Sockets, 8-29 

get_deps function, xgmon, 6-23 

get_MIB_base_type subroutine, 6-24 

get_MIB_group function, xgmon, 6-25 

get_MIB_name subroutine, 6-27 

get_MIB_variable_type subroutine, 6-28 

get_myaddress subroutine, RPC, 5-46 

get_primary function, xgmon, 6-30 

getc subroutine, 1-174—1-—175 

getchar subroutine, 1—-174—1-175 

getcwd subroutine, 1-176 

getdomainname subroutine, Sockets, 8-23 

getdtablesize subroutine, 1-177 

getegid subroutine, 1-180 

getenv function, xgmon, 6-31 

getenv subroutine, 1-178 

geteuid subroutine, 1-226 

getfsenct subroutine, 1-179 
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getfisspec subroutine, 1-179 

getfstype subroutine, 1-179 

getgid subroutine, 1-180 

getgidx subroutine, 1-181 

getgrent subroutine, 1-182—1-183 
getgrgid subroutine, 1-182—1-—183 
getgrnam subroutine, 1-182—1-183 
getgroupattr subroutine, 1-184—1—187 
getgroups subroutine, 1-188—1-—189 
gethostbyaddr subroutine, Sockets, 8—24 
gethostbyname subroutine, Sockets, 8-26 
gethostent subroutine, Sockets, 8-28 
gethostid subroutine, Sockets, 8-29 
gethostname subroutine, Sockets, 8-30 
getinterval subroutine, 1-190—1-192 
getitimer subroutine, 1-190—1-192 
getlogin subroutine, 1-193 

_getlong subroutine, Sockets, 8-31 
getnetbyaddr subroutine, Sockets, 8-33 
getnetbyname subroutine, Sockets, 8-35 
getnetent subroutine, Sockets, 8-37 
getnetname subroutine, RPC, 5-47 
getopt subroutine, 1-194—1-195 
getpagesize subroutine, 1-196 

getpass subroutine, 1-197 

getpcred subroutine, 1-198—1-199 
getpeername subroutine, Sockets, 8-38 
getpenv subroutine, 1-200—1-201 
getpgrp subroutine, 1-202 

getpid subroutine, 1-202 

getppid subroutine, 1-202 

getpri subroutine, 1-203 

getpriority subroutine, 1-204—1-—205 
getprotobyname subroutine, Sockets, 8-40 
getprotobynumber subroutine, Sockets, 8-42 
getprotoent subroutine, Sockets, 8—44 
getpwent subroutine, 1-206—1-207 
getpwnam subroutine, 1-206—1-—207 
getpwuid subroutine, 1-206—1-—207 
getrlimit subroutine, 1-208—1-210 
getrusage subroutine, 1-211—1-213 
gets subroutine, 1-214 

gets the name of the local host, Sockets, 8—30 
getservbyname subroutine, Sockets, 8—46 
getservbyport subroutine, Sockets, 8—48 
getservent subroutine, Sockets, 8-50 
getsfile subroutine, 1-179 

_getshort subroutine, Sockets, 8-52 
getsockname subroutine, Sockets, 8—54 
getsockopt subroutine, Sockets, 8-56 
getssys subroutine, 1-215 

getsubsvr subroutine, 1-216—1-—217 
gettimeofday subroutine, 1-218—1-—219 
gettimer subroutine, 1—-220—1-—221 
gettimerid subroutine, 1-222—1-—223 
gettyent subroutine, 1-224—1-—225 
gettynam subroutine, 1-224—1-225 
getuid subroutine, 1-226 

getuidx subroutine, 1-227 


getuinfo subroutine, 1-228 
getuserattr subroutine, 1—-229—1-234 
getuserpw subroutine, 1-235—1-—236 
getutent subroutine, 1-237—1—239 
getutid subroutine, 1-237—1-239 
getutline subroutine, 1-237—1-239 
getvfsbyname subroutine, 1-240—1-241 
getvfsbytype subroutine, 1-240—1-241 
getvfsent subroutine, 1-240—1-241 
getw subroutine, 1-174—1-175 
getwc subroutine, 1-242 
getwchar subroutine, 1-242 
getwd subroutine, 1-243 
getws subroutine, 1-244—1-245 
Global Location Broker 
looking up information, 4—5 
looking up interface information, 4-3 
looking up type information, 4—12 
gmtime subroutine, 1-101—1-103 
group access list 
getting, using getgroups subroutine, 
1-—188—1-189 
initializing, using initgroups subroutine, 1-281 
group file, accessing 
using endgrent subroutine, 1-182—1-183 
using getgrent subroutine, 1-182—1-183 
using getgrgid subroutine, 1—-182—1-—183 
using getgrnam subroutine, 1-182—1-183 
using putgrent subroutine, 1-182—1-183 
using setgrent subroutine, 1-182—1-183 
group LAF statements, HCON programming, 2-8 
group_dep function, xgmon, 6-32 
gsignal subroutine, 1-704—1-705 
gtty subroutine, 1-723 
gw_var function, xgmon, 6-34 


H 


halt a link station, DLC, 3-39 
halt a link station’s result extension, DLC, 3-56 
handles 
clearing binding, 4-32 
copying, 4-31 
determining objects, 4—34 
HCON programming commands 
genprof, 2-62 
mtlaf, 2-86 
HCON programming functions 
cfxfer, 2—4 
fxfer, 2-11 
g32_alloc, 2-17 
g32_close, 2-21 
g32_dealloc, 2-24 
g32_fxfer, 2-29 
g32_get_cursor, 2-37 
g32_get_data, 2-40 
g32_get_status, 2-43 
g32_notify, 2-46 
g32_open, 2—49 


g32_openx, 2-55 
g32_read, 2-65 
g32_search, 2-69 
g32_send_keys, 2-74 
g32_write, 2-80 
G32ALLOC, 2-15 
G32DLLOC, 2-27 
G32WRITE, 2-78 
HCON programming LAF statements 
BREAK, 2-3 
DEBUG, 2-7 
DO-END, 2-8 
EXIT, 2-9 
FINISH, 2—10 
IF—ELSE, 2-83 
MATCH, 2-84 
MATCHAT, 2-85 
RECEIVE, 2-87 
RECVAT, 2-89 
REPEAT-—UNTIL, 2-90 
SELECT, 2-91 
SEND, 2-93 
START, 2-94 
WAIT, 2-95 
WHILE, 2-97 
hcreate subroutine, 1-246 
hdestroy subroutine, 1-246 
hexval function, xgmon, 6-36 
highlight_dep function, xgmon, 6-37 
host API application, HCON programming 
end interaction with, 2-24 
initiating interaction with. See G32DEALLOC 
Function 
host application, HCON programming, receive 
message from, 2—65 
host data, HCON programming 
receiving and searching for pattern match in 
presentation space, 2-87 
receiving and searching for pattern match in 
specified position of presentation space, 2-89 
host2netname subroutine, RPC, 5-48 
hostname function, xgmon, 6-39 
hsearch subroutine, 1-246 
htonl subroutine, Sockets, 8—60 
htons subroutine, Sockets, 8-61 
hypot subroutine, 1-248—1-—249 


|-frame data received routine, DLC, 3-65 
I/O errors, inquire about, using ferror macro, 1-140 
ID, getting the process group 
using getegid subroutine, 1-180 
using getgid subroutine, 1-180 
IDtogroup subroutine, 1-184—1-—187 
IDtouser subroutine, 1-229—1-234 
IEEE Math Library 
acos subroutine, 1-673—1-—674 
acosh subroutine, 1-26 
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asin subroutine, 1-673—1-674 
asinh subroutine, 1-26 
atan subroutine, 1-673—1-674 
atan2 subroutine, 1-673—1-674 
atanh subroutine, 1-26 
cabs subroutine, 1-248—1-—249 
cbrt subroutine, 1-676 
ceil subroutine, 1-141—1-143 
copysign subroutine, 1-94—1-—95 
cos subroutine, 1-673—1-674 
cosh subroutine, 1-675 
erf subroutine, 1-118 
erfc subroutine, 1-118 
exp subroutine, 1-129—1-131 
expm1 subroutine, 1-129—1-131 
fabs subroutine, 1-141—1-143 
floor subroutine, 1-141—1-143 
fmod subroutine, 1—-141—1-143 
gamma subroutine, 1-322—1-323 
hypot subroutine, 1-248—1-249 
ilogb subroutine, 1-94—1-—95 
Itrunc subroutine, 1-141—1-143 
jO subroutine, 1-50—1-51 
j1 subroutine, 1-50—1-—51 
jn subroutine, 1-50—1-51 
Igamma subroutine, 1—-322—1-323 
log subroutine, 1-129—1-131 
log10 subroutine, 1-129—1-131 
logip subroutine, 1-129 
logb subroutine, 1-94—1-95 
nearest subroutine, 1-141—1-143 
nextafter subroutine, 1-94—1-—95 
pow subroutine, 1-129—-1-131 
rint subroutine, 1-141—1-143 
scalb subroutine, 1-94—1-95 
sin subroutine, 1-673—1-674 
sinh subroutine, 1-675 
sqrt subroutine, 1-676 
tan subroutine, 1-673—1-674 
tanh subroutine, 1-675 
trunc subroutine, 1-141—1-143 
uitrunc subroutine, 1-141—1-143 
yO subroutine, 1-50—1-—51 
y1 subroutine, 1-50—1-—51 
yn subroutine, 1-50—1-—51 
IF-ELSE LAF statement, HCON programming, 2-83 
ilogb subroutine, 1-94—1-95 
IMAIXMapping subroutine, 1-250 
IMAuxCreate subroutine, 1-251 
IMAuxDestroy subroutine, 1-252 
IMAuxDraw, drawing auxiliary area, using 
IMAuxDraw subroutine, 1-253 
IMAuxDraw Callback Function, 1-253 
IMAuxHide Callback Function, 1-254 
IMBeep subroutine, 1-255 
imcalloc subroutine, 1-256 
IMClose subroutine, 1-257 
IMCreate subroutine, 1-258 
JMDestroy subroutine, 1-259 


X-10 Base Operating System Reference 


IMFEP, clearing IMObject, using IMTextHide 
subroutine, 1-279 
imfree subroutine, 1-260 
IMFreeKeymap subroutine, 1-261 
IMindicatorDraw subroutine, 1-262 
IMindicatorHide subroutine, 1-263 
IMInitialize subroutine, 1-264 
iMInitializeKeymap subroutine, 1-265 
IMloct! subroutine, 1-266—1-267 
immalloc subroutine, 1-268 
IMObject, destroying, using |MDestroy subroutine, 
1-259 
IMObject pointer, creating, using IMCreate 
subroutine, 1-258 
IMProcess subroutine, 1-269—1-270 
IMProcessAuxiliary subroutine, 1-271—1-—272 
IMQueryLanguage subroutine, 1-273 
imrealloc subroutine, 1-274 
IMRebindCode subroutine, 1-275 
IMSimpleMapping subroutine, 1-276 
IMTextCursor Callback Function, 1-277 
IMTextDraw subroutine, 1-278 
IMTextHide Subroutine, 1-279 
IMTextStart subroutine, 1-280 
imul_dbl subroutine, 1-5 —1-6 
incinterval subroutine, 1-190—1-—192 
index subroutine, 1-717 
inet_addr subroutine, Sockets, 8-62 
inet_Inaof subroutine, Sockets, 8-64 
inet_makeaddr subroutine, Sockets, 8-66 
inet_netof subroutine, Sockets, 8-68 
inet_network subroutine, Sockets, 8-70 
inet_ntoa subroutine, Sockets, 8-72 
initgroups subroutine, 1-281 
initialize GDLC device manager, 3-6 
initiate file transfer within an executing AIX program, 
“~HCON programming, 2-11 
initiate interaction with host application, HCON 
programming, 2-17 
initstate subroutine, 1-566—1—567 
input 
assigning buffering, using setbuf subroutine, 
1-610—1-611 
binary, using fread subroutine, 1-159—1-—160 
getting a character 
using fgetc subroutine, 1-174—1-175 
using fgetwc subroutine, 1-242 
using getc subroutine, 1-174—1-—175 
using getchar subroutine, 1-174—-1-175 
using getw subroutine, 1-174—1-—175 
using getwc subroutine, 1-242 
using getwchar subroutine, 1-242 
AIX Input Method, initializing the IMFepRec 
structure, using IMInitialize subroutine, 1-264 
Input Method 
Callback functions 
IMAuxCreate, 1-251 
IMAuxDestroy, 1-252 
IMAuxDraw, 1-253 


IMAuxHide, 1-254 
IMBeep, 1-255 
IMIndicatorDraw, 1-262 
IMindicatorHide, 1-263 
IMTextCursor, 1-277 
IMTextDraw, 1-278 
IMTextHide, 1-279 
IMTextStart, 1-280 
closing, using IMClose subroutine, 1-257 
Input Method Library 
IMAIXMapping subroutine, 1-250 
imcalloc subroutine, 1-256 
IMClose subroutine, 1-257 
IMCreate subroutine, 1-258 
IMDestroy subroutine, 1-259 
imfree subroutine, 1-260 
IMFreeKeymap, 1-261 
IMinitialize subroutine, 1-264 
IMinitializeKeymap subroutine, 1-265 
IMloctl subroutine, 1-266 
immalloc subroutine, 1-268 
IMProcess subroutine, 1-269 
IMProcessAuxiliary subroutine, 1-271 
IMQueryLanguage subroutine, 1-273 
imrealloc subroutine, 1-274 
IMRebindCode subroutine, 1-275 
IMSimpleMapping subroutine, 1-276 
input stream 
check status 
using clearerr macro, 1-140 
using fileno macro, 1-140 
getting a string 
fgetws subroutine, 1-244—1-245 
getws subroutine, 1-244—1-245 
pushing a character back into, using ungetc, 
ungetwc subroutines, 1-779—1-—780 
reading characters 
fgets subroutine, 1-214 
gets subroutine, 1-214 
insque subroutine, 1-282 
interfaces 
looking up information in GLB, 4-3 
registering with Location Broker, 4—14 
unregistering, 4—42 
interprocess channel, create, using pipe subroutine, 
1-530 
interrupt LAF script to wait until data receive from 
host, HCON programming, 2—95 
interrupt loop in LAF script, HCON programming, 
interrupt packet for X.25, sending, using 
x25_interrupt subroutine, 9-20 
interval timer 
allocating per—process, using gettimerid 
subroutine, 1-222—1-223 
manipulating the expiration time 
using absinterval subroutine, 
1-—190—1-192 
using alarm subroutine, 1-190—1-—192 


using getinterval subroutine, 
1-190—1-192 
using getitimer subroutine, 1-190—1-192 
using incinterval subroutine, 1-190—1-—192 
using resabs subroutine, 1-190—1-192 
using resinc subroutine, 1-190—1-192 
using setitimer subroutine, 1-190—1-192 
using ualarm subroutine, 1-190—1-—192 
releasing, using reltimerid subroutine, 1-582 


intrinsic functions, xgmon 


database operations 
base_type, 6-6 
getenv, 6-31 
get_MIB_group, 6—25 
gw_var, 6-34 
real_type, 6-61 
setenv, 6-73 
snmp_var, 6-76 
file /O 
close, 6-7 
fopen, 6-21 
read, 6-60 
formatted output 
num, 6-55 
sprintf, 6-77 
graphics functions 
dep_info, 6-10 
draw_line, 6-13 
draw_string, 6-14 
font_height, 6-19 
font_width, 6-20 
get_deps, 6-23 
group_dep, 6-32 
highlight_dep, 6-37 
make_dep, 6-47. 
make_link, 6-48 
move_dep, 6-52 
new_deps, 6-53 
raise_window, 6-59 
rename_dep, 6-62 
set_element_mask, 6-71 
window_height, 6-82 
window_width, 6-83 
host information 
dotaddr, 6-12 
get_primary, 6-30 
hostname, 6-39 
ipaddr, 6—40 
next_alternate, 6-54 
password, 6-57 
ping, 6-58 
string manipulation 
ascii, 6-5 
hexval, 6-36 
left, 6-41 
mid, 6-51 
right, 6-64 
strlen, 6-78 
substr, 6-79 


Index X—11 


val, 6-81 
virtual G machine (VGM) control 

aix_exec, 6-3 

alloc, 6-4 

ctime, 6—9 

exec, 6-16 

flush_trap, 6-18 

reuse_mem, 6-63 

time, 6-80 

words free, 6-84 
invert subroutine, 1-396 
invoke a file transfer, HCON programming, 2-29 
iocinfo ioctl operation, DLC, 3-57 
ioctl operations, DLC, parameter blocks, 3-32 
ioctl operations, DLC, 3-30 
ioctl subroutine, DLC, 3-28 
ioctl subroutine for generic SNA, SNA, 7-15 
ioctl subroutine for SNA Services/6000, SNA, 7-6 
ioctl subroutines, 1-283 
ioctlx subroutines, 1-283 
ipaddr function, xgmon, 6-40 
isalnum subroutine, 1-104 
isalpha subroutine, 1-104 
isascii subroutine, 1-104 
isatty subroutine, 1-770 
iscntrl subroutine, 1-104 
isdigit subroutine, 1-104 
isgraph subroutine, 1-104 
isjalnum subroutine, 1-287 
isjalpha subroutine, 1-287 
isjdigit subroutine, 1-287 
isjgraph subroutine, 1-287 
isjhira subroutine, 1-288 
isjis subroutine, 1-287 
isjkanji subroutine, 1-288 
isjkata Subroutine, 1-288 
isjlbytekana subroutine, 1-287 
isjlower subroutine, 1-287 
isjparen subroutine, 1-287 
isjprint subroutine, 1-287 
isjpunct subroutine, 1-287 
isjspace subroutine, 1-287 
isjupper subroutine, 1-287 
isjxdigit subroutine, 1-287 
islower subroutine, 1-104 
isnan subroutine, 1-82—1-83 
isparent subroutine, 1-287 
isprint subroutine, 1-104 
ispunct subroutine, 1-104 
isspace subroutine, 1-104 
isupper subroutine, 1-104 
isxdigit Subroutine, 1-104 
itom subroutine, 1-396 
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jO subroutine, 1-50—1-51 
j1 subroutine, 1-50—1-51 


Japanese Language Support, varargs parameter list, 


format and print, 1-481 
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jistoa subroutine, 1-285 

jistosj subroutine, 1-292—1-—293 
jistouj subroutine, 1-292—1—-293 
jn subroutine, 1-50—1-51 
jrand48 subroutine, 1-111—1-113 


K 


key_decryptsession subroutine, RPC, 5—49 

key_encryptsession subroutine, RPC, 5-50 

key_gendes subroutine, RPC, 5-51 

key_setsecret subroutine, RPC, 5-52 

keymap, intializing, using IMInitializeKeymap 
subroutine, 1-265 

kill subroutine, 1-294—1—-295 

killpg subroutine, 1-294—1-—295 

kleenup subroutine, 1-296 

knlist subroutine, 1-297—1—298 

kutentojis subroutine, 1-285 


L 


I3tol subroutine, 1-299 
\64a subroutine, 1-3 
labs subroutine, 1-5——1-6 
LAF script, HCON programming 
ending, 2-10 
executing subject statement in, 2-90 
executing subject statements in, 2-97 
grouping statements, 2-8 
interrupt loop in, 2-3 
interrupting to wait for host data, 2-95 
sending key string to emulator and host, 2-93 
starting, 2-94 
terminating execution of, 2-9 
testing for conditional execution (two—way), 
2-83 
testing for conditional execution of (multiple 
alternative), 2-91 
language specific input processing, using the 
IMProcess subroutine, 1-269 
lb_ $lookup_interface library routine, NCS, 4-3 
lb_ $lookup_object library routine, NCS, 4—5 
lb_$lookup_object_local library routine, NCS, 4-7 
lb_ $lookup_range library routine, NCS, 4—9 
Ib_$lookup_type library routine, NCS, 4-12 
lb_$register library routine, NCS, 4-14 
lb_$unregister library routine, NCS, 4-16 
Icong48 subroutine, 1-111—1-113 
Idaclose subroutine, 1-301 
Idahread subroutine, 1-300 
Idaopen subroutine, 1-311 
Idclose subroutine, 1-301 
Idexp subroutine, 1-163—1~—164 
Idfhread subroutine, 1-303 
Idgetname subroutine, 1-304 
Idiv subroutine, 1-5—-1-6 
Idlinit subroutine, 1-306 
Idlitem subroutine, 1-306 
Idiread subroutine, 1-306 


Ildilseek subroutine, 1-308 
ldniseek subroutine, 1-308 
ldnrseek subroutine, 1-313 
Idnshread subroutine, 1-315 
ldnsseek subroutine, 1-317 
idohseek subroutine, 1-310 
Idopen subroutine, 1-311 
ldrseek subroutine, 1-313 
Idshread subroutine, 1-315 
Idsseek subroutine, 1-317 
Idtbindex subroutine, 1-319 
ldtbread subroutine, 1-320 
Idtbseek subroutine, 1-321 
left function, xgmon, 6—41 
lfind subroutine, 1-339 
Igamma subroutine, 1-322—1-323 
link, create additional, for existing file, 1-324—1-325 
link subroutine, 1-324—1-—325 
listen for and limit socket connections, Sockets, 8-74 
listen subroutine, Sockets, 8-74 
load and bind object module, 1-326—1-328 
load subroutine, 1-326—1-328 
loadbind subroutine, 1-329—1-330 
loadquery subroutine, 1-331 
locale, changing, using the setlocale subroutine, 
1-619—1-620 
localeconv subroutine, 1-333—1-335 
localtime subroutine, 1-101—1-103 
Location Broker 
looking up information, 4-7 
registering objects and interfaces, 4-14 
removing entries from database, 4-16 
routines. See Ib_§$ library routines 
lock, process, text, or data in memory, using plock 
subroutine, 1-531—1-532 
lockf subroutine, 1-336—1-338 
lockfx subroutine, 1-336—1-—338 
log subroutine, 1-129—1-131 
log10 subroutine, 1-129—1-—131 
log1p subroutine, 1-129—1-131 
logb subroutine, 1-94—1-95 
logical path, HCON programming, returning status 
information of, 2-43 
logical volume 
changing attributes, using lvm_changelv 
subroutine, 1-343—1-345 
changing physical volume attributes, using 
livm_changepv subroutine, 1-346—1-348 
creating a new volume group, lvm_createvg 
subroutine, 1-352—1-354 
creating empty volume, using lvm_createlv 
subroutine, 1-349—1-351 
deleting a physical volume, using lvm Edelelepy 
subroutine, 1-357—1-358 
deleting from its volume group, using 
lvm_deletelv subroutine, 1-355—1-356 
extending specified number of partitions, using 
ivm_extendlv subroutine, 1-359—1-362 


installing physical volume, using lvm_installpv 
subroutine, 1-363—1~—365 
moving a physical partition, using 
lvm_migratepp, 1-366—1-367 
querying for pertinent information, using 
lvm_querylv subroutine, 1-368—1-371 
querying volume group, using lvm_queryvg 
subroutine, 1-375—1-377 
querying volume groups for ids, using 
lvm_queryvgs subroutine, 1-378—1-379 
reducing number of partitions, using 
lvm_reducelv subroutine, 1-380—1-382 
synchronizing all physical partitions, using 
lvm_resyncip subroutine, 1-383—1-—384 
synchronizing physical copies of logical 
partition, using lvm_resynclv subroutine, 
1-385—1-—386 
synchronizing physical partitions, using 
lvm_resyncpv subroutine, 1-387—1-388 
varying a volume group on-line, using 
lvm_varyonvg subroutine, 1-391—1-395 
varying volume group off-line, using 
lvm_varyoffvg subroutine, 1-389—1-—-390 
Logical Volume Manager Library, 1-366—1-367 
lvm_changelv subroutine, 1-3438-—1-345 
lvm_changepv subroutine, 1-346—1-348 
lvm_createlv subroutine, 1-349—1-351 
lvm_createvg subroutine, 1-352—1-354 
lvm_deletelv subroutine, 1-355—1—-356 
lvm_deletepv subroutine, 1-357—1-358 
lvm_extendlv subroutine, 1-359—1-362 
lvm_installpv subroutine, 1-363—1-365 
lvm_querylv subroutine, 1-368—1-371 
lvm_querypv subroutine, 1-372—1-374 
lvm_queryvg subroutine, 1-375—1-377 
lvm_queryvgs subroutine, 1-378-—1-379 
lvm_reducelv subroutine, 1-380—1-382 
lvm_resyncip subroutine, 1-383—1—-384 
lvm_resynclv subroutine, 1-385—1-—386 
lvm_resyncpv subroutine, 1-387—1-388 
lvm_varyoffvg subroutine, 1-389—1-390 
lvm_varyonvg subroutine, 1-391—1-395 
login name, getting, using getlogin subroutine, 1-193 
longjmp subroutine, 1-617—1-618 
lookup_addr subroutine, 6—42 
lookup_host subroutine, 6-43 
lookup_SNMP_ group subroutine, 6-44 
lookup_SNMP_name subroutine, 6-46 
lrand48 subroutine, 1-111—-1-113 
Isearch subroutine, 1-339 
Iseek subroutine, 1-341 
Itol3 subroutine, 1-299 
luOapi subroutine, SNA, 7-17 
juOclosep subroutine, SNA, 7-20 
luOcloses subroutine, SNA, 7-21 
luOctlp subroutine, SNA, 7-22 
luOctls subroutine, SNA, 7-24 
luQopenp subroutine, SNA, 7-26 
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luOopens subroutine, SNA, 7—27 
luOreadp subroutine, SNA, 7—28 
luOreads subroutine, SNA, 7-29 
luOwritep subroutine, SNA, 7-30 
luOwrites subroutine, SNA, 7-32 
lvm_changelv subroutine, 1-343—1-345 
lvm_changepv subroutine, 1-346—1-348 
lvm_createlv subroutine, 1-349—1-351 
lvm_createvg subroutine, 1-352—1-354 
lvm_deletelv subroutine, 1—355—1-356 
lvm_deletepv subroutine, 1-357—1-—358 
lvm_extendlv subroutine, 1-359—1-362 
lvm_installpv subroutine, 1-363—1-365 
lvm_migratepp subroutine, 1-366—1-—367 
lvm_querylv subroutine, 1-368—1-371 
lvm_querypv subroutine, 1-372—1-374 
lvm_queryvg subroutine, 1-375—1-377 
lvm_queryvgs subroutine, 1-378—1-379 
lvm_reducelv subroutine, 1-380—1-—382 
lvm_resynclp subroutine, 1-383—1-—384 
lvm_resynclv subroutine, 1-385—1-386 
lvm_resyncpv subroutine, 1-387—-1-388 
lvm_varyoffvg subroutine, 1-389—1-—390 
lvm_varyonvg subroutine, 1-391—1-—395 


M 


m_in subroutine, 1-396 
m_out subroutine, 1-396 
madd subroutine, 1-396 
make an Internet address, 8-66 
make query messages for name servers, Sockets, 
8-93 
make storage space available, xgmon, 6—4 
make_dep function, xgmon, 6—47 
make_link function, xgmon, 6-48 
make_SNMP_request subroutine, 6—49 
mallinfo subroutine, 1-399—1-—402 
malloc subroutine, 1-399——1—402 
mallopt subroutine, 1-399—1—-402 
manage socket descriptors for processes, 
yp_unbind, 5-143 
map node or host to topology display window, 
xgmon, 6-32 
MATCH LAF statement, HCON programming, 2-84 
MATCHAT LAF statement, HCON programming, 
2-85 
Math Library 
class subroutine, 1-82—1-83 
drem subroutine, 1-114 
finite subroutine, 1-82—1-83 
isnan subroutine, 1-82—1-83 
unordered subroutine, 1-82—1-—83 
matherr subroutine, 1-403 
mblen subroutine, 1-405 
mbscat subroutine, 1-406 
mbschr subroutine, 1-407 
mbscmp subroutine, 1-406 
mbscpy subroutine, 1-406 
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mbslen subroutine, 1-408 
mbsncat subroutine, 1-409 
mbsncmp subroutine, 1-409 
mbsncpy subroutine, 1-409 
mbspbrk subroutine, 1-410 
mbsrchr subroutine, 1-411 
mbstoint subroutine, 1-412 
mbstowcs subroutine, 1-413 
mbtowc subroutine, 1-414 
mcmp subroutine, 1-396 
mdiv subroutine, 1-396 
memcecpy subroutine, 1-415—1-416 
memchr subroutine, 1—-415—1—416 
memcemp subroutine, 1-415—1-—416 
memepy subroutine, 1-415—1-416 
memmove subroutine, 1-415—1-—416 
memory block 
changing size, using imrealloc subroutine, 
1-274 
freeing, using imfree subroutine, 1-260 
returning number of bytes, using immalloc 
subroutine, 1-268 
memory management 
allocate memory, 1-399—1-—402 
attach mapped file, 1-641—1-643 
attach shared memory segment, 
1-641—1-643 
change data segment allocation, 1-52—1-—53 
detach shared memory segment, 1-647 
get paging device status, 1-726 
get shared memory segments, 1-648—1-—650 
get system page size, 1-196 
mark unneeded memory, 1-110 
memory operations, 1-415 
paging and swapping, 1-725 
shared memory operations, 1-644—1-—-646 
memset subroutine, 1-415—1—416 
message 
interprocess communication identifiers, 
1-170—1-171 
send to queue, using msgsnd subroutine, 
1-448 
message control, using msgct! subroutine, 
1-—440—1-442 
message facility 
close catalog, 1-56 
copy message to buffer, 1-57 
initial catalog access, 1-462 
open catalog, 1-59—1-60 
open catalog, get message, close catalog, 
1-468 
retrieve message, 1-58 
message queue, reading a message, using msgrcv 
subroutine, 1-445—1-—447 
message queue identifier, get, using msgget 
subroutine, 1-443—1-444 
message queues, checking I/O status, using poll 
subroutine, 1-535—1-536 


mid function, xgmon, 6-51 
min subroutine, 1-396 
mkdir subroutine, 1-417—1-418 
mkfifo subroutine, 1-419—1-—420 
mknod subroutine, 1-419—1-—420 
mkstemp subroutine, 1-421—1-422 
mktemp subroutine, 1-421—1-—422 
mktime subroutine, 1-101—1-103 
mnictl subroutine, 1-423—1-424 
modf subroutine, 1-163—1-164 
moncontrol subroutine, 1-425—1-—426 
monitor subroutine, 1-427—1-—435 
monstartup subroutine, 1-436—1-—439 
mount a file system, using vmount subroutine, 1-790 
mount subroutine, 1-790—1-793 
mounted file system, get mount status, using mnitctl 
subroutine, 1-423 
mout subroutine, 1-396 
move subroutine, 1-396 
move_dep function, xgmon, 6-52 
mrand48 subroutine, 1-111—1-113 
msgctl subroutine, 1-440—1-—442 
msgget subroutine, 1-443—1-444 
msgrcv subroutine, 1-445—1-447 
msgsnd subroutine, 1-448—1-—449 
msgxrcv subroutine, 1-450—1-—452 
msart subroutine, 1-396 
msub subroutine, 1-396 
mtlaf command, HCON programming, 2-86 
mult subroutine, 1-396 
multibyte character string 
appending code points, using mbscat 
subroutine, 1-406 
comparing characters, using mbscmp 
subroutine, 1-406 
copying characters, using mbscpy subroutine, 
1-406 
determining code points, using mbslen 
subroutine, 1-408 
extracting multibyte character, using mbstoint 
subroutine, 1-412 
locating a code point, using mbsrchr 
subroutine, 1-411 
locating code point, using mbschr subroutine, 
1-407 
locating first code points, using mbspbrk 
subroutine, 1-410 
multibyte characters, null-terminated 
appending value, using mbsncat subroutine, 
1-409 
comparing values, using mbsncmp subroutine, 
1-409 
copying values, using mbsncpy subroutine, 
1-409 
multiple alternative test for conditional execution of 
LAF statements, HCON programming, 2-91 


N 


name list, get entries from, 1-469—-1—470 
national language, returning information on, using 
nl_langinfor subroutine, 1-471 
NCchrlen subroutine, 1-463 
NCdecode subroutine, 1-463 
NCdecstr subroutine, 1-463 
NCencode subroutine, 1-463 
NCencstr subroutine, 1-463 
NCisalnum subroutine, 1-453 
NCisalpha subroutine, 1-453 
NCiscntri subroutine, 1-453 
NCisdigit subroutine, 1-453 
NCisgraph subroutine, 1-453 
NCislower subroutine, 1-453 
NCisNLchar subroutine, 1-453 
NCisprint subroutine, 1-453 
NCispunct subroutine, 1-453 
NCisspace subroutine, 1-453 
NCisupper subroutine, 1-453 
NCisxdigit subroutine, 1-453 
NCS library routines 
lb_ $lookup_interface, 4-3 
lb_$lookup_object, 4-5 
lb_ $lookup_object_local, 4—7 
lb_$lookup_range, 4-9 
lb_$lookup_type, 4-12 
lb_$register, 4-14 
lb_Sunregister, 4-16 
pfm_$cleanup, 4-17 
pfm_$enable, 4-19 
pfm_$enable_faults, 4-20 
pfm_$inhibit, 4-21 
pfm_$inhibit_faults, 4-22 
ofm_S$init, 4-23 
pfm_$reset_cleanup, 4—24 
pfm_$rls_cleanup, 4-25 
pfm_$signal, 4-26 
rpc_$alloc_handle, 4-27 
rpc_$bind, 4-28 
rpc_$clear_binding, 4-29 
rpc_$clear_server_binding, 4-30 
rpc_$dup_handle, 4-31 
rpc_$free_handle, 4-32 
rpc_$ing_binding, 4-33 
rpc_$ing_object, 4-34 
rpc_$listen, 4-35 
rpc_$name_to_sockaddr, 4-36 
rpc_$register, 4-38 
rpc_$set_binding, 4—40 
rpc_$sockaddr_to_name, 4—41 
rpc_$unregister, 4-42 
rpc_$use_family, 4-43 
rpc_$use_family_wk, 4-45 
uuid_$decode, 4—47 
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uuid_$encode, 4—48 
uuid_$gen, 4-49 
NCstrcat subroutine, 1-456 
NCstrchr subroutine, 1-456 
NCstrepy subroutine, 1-456 
NCstrcspn subroutine, 1-456 
NCstrdup subroutine, 1-457 
NCstrlen subroutine, 1-456 
NCstrncat subroutine, 1-456 
NCstrncmp subroutine, 1-456 
NCsirncpy subroutine, 1-456 
NCstrpbrk subroutine, 1-456 
NCstrrchr subroutine, 1-456 
NCstrspn subroutine, 1-456 
NCstrtok subroutine, 1-456 
NCwunesc subroutine, 1-285 
NDBM 
dbm_close subroutine, 5-34 
dbm_delete subroutine, 5-35 
dbm_fetch subroutine, 5-36 
dbm_firstkey subroutine, 5-37 
dbm_nextkey subroutine, 5-38 
dbm_open subroutine, 5-39 
dbm_store subroutine, 5-40 
nearest subroutine, 1-141—1-143 
netname2host subroutine, RPC, 5-53 
netname2user subroutine, RPC, 5-54 
network data received routine, DLC, 3-66 
new_deps function, xgmon, 6-53 
newpass Subroutine, 1-460—1-461 
next_alternate function, xgmon, 6-54 
nextafter subroutine, 1-94—1-95 
nextgroup subroutine, 1-184—1-—187 
nextkey subroutine, 5-55 
nice subroutine, 1-204—1-—205 
NIS 
yp_all subroutine, 5-131 
yp_bind subroutine, 5—133 
yp_first subroutine, 5-135 
yp_get_default_domain subroutine, 5-137 
yp_master subroutine, 5-138 
yp_match subroutine, 5-139 
yp_next subroutine, 5-140 
yp_order subroutine, 5-142 
yp_unbind subroutine, 5-143 
yp_unpdate subroutine, 5-144 
yperr_string subroutine, 5-146 
ypprot_err subroutine, 5—147 
nl_langinfo subroutine, 1-471 
NLcatgets subroutine, 1-462 
NLcatopen subroutine, 1-59—1-60 
NLchar data type, handling using NLchar 
subroutines, 1-463—1-—464 
NLchrien subroutine, 1-463 
NLeplen subroutine, 1-465 
NLescstr subroutine, 1-466— 1-467 
NLflatstr subroutine, 1-466—1-467 
NLfprintf subroutine, 1-538—1-543 
NLfscanf subroutine, 1-593—1—-597 


X-16 Base Operating System Reference 


NLgetamsg subroutine, 1-468 
NLgetenv subroutine, 1-178 
NLisNLcp subroutine, 1-463 
nlist subroutine, 1-469—1~-470 
NLprintf subroutine, 1-538—1—-543 
NLscanf subroutine, 1-593—1-597 
NLsprintt subroutine, 1-538—1-—543 
NLsscanf subroutine, 1-593—1-—597 
NLstrcat subroutine, 1-472, 1-473 
NLstrchr subroutine, 1-472, 1-474 
NLstremp subroutine, 1-456, 1-472, 1-473 
NLstrcpy subroutine, 1-472, 1-473 
NLstrespn subroutine, 1-472, 1-474 
NLstrdien subroutine, 1-472, 1-474 
NLstrien subroutine, 1-473 
NLstrlen subroutine, 1-472 
NLstrncat subroutine, 1-472, 1-473 
NLstrncmp subroutine, 1-472, 1-473 
NLstrncpy subroutine, 1-472, 1-473 
NLstrpbrk subroutine, 1-472, 1-474 
NLstrrchr subroutine, 1-472, 1-474 
NLstrspn subroutine, 1-472, 1-474 
NLstrtime subroutine, 1-475—1—477 
NLstrtok subroutine, 1-472, 1-474 
NLtmtime subroutine, 1-478—1-—480 
NLunescstr subroutine, 1—-466—1-467 
NLvfprintf subroutine, 1-481 
NLvprintf subroutine, 1-481 
NLvsprintf subroutine, 1-481 
NLxin subroutine, 1-482—1—483 
NLxout subroutine, 1-484 
NLxstart subroutine, 1-485 
NLyesno subroutine, 1-486 
nm_close subroutine, SNA, 7-34 
nm_open subroutine, SNA, 7~35 
nm_receive subroutine, SNA, 7-36 
nm_send subroutine, SNA, 7-38 
nm_status subroutine, SNA, 7-40 
normal sequenced data packet received call, DLC, 
3-65 
nrand48 subroutine, 1-111—1-113 
nsleep subroutine, 1-487—1-488 
ntohl subroutine, Sockets, 8-76 
ntohs subroutine, Sockets, 8-77 
num function, xgmon, 6-55 
numeric data, machine—independent access, 1—640 
numerical data, generating pseudo-random 
numbers, 1-111—1-113 
numerical data 
absolute value, division, and double-precision 
multiplication, 1-5 1-6 
ASCIl string to float or double floating—point 
number, 1—28—1-29 
Bessel functions, 1-50—1~—51 
binary floating-point arithmetic, 1-94—1-95 
classification of floating-point numbers, 
1-82—1-83 
convert 3-byte integers and long integers, 
1-299 


convert floating-point number to string, 
1-115—1-116 

convert long integers and base-64 ASCII 
strings, 1-3 

convert NLchar string to double-precision 
floating-point, 1-819—1-820 

convert string to integer, 1-721—1-—722 

converting NLchar string to integer, 
1-821—1-822 

error and complementary error functions, 1-118 

Euclidean distance function and complex 
absolute value, 1-248—1-249 

exponential, logarithm, and power functions, 
1-129—1-131 

floating-point absolute value, 1-141—1-143 

generating better pseudo-random numbers, 
1-566—1-567 

generating pseudo-random numbers, 
1-564—1-565 

handling math errors, 1-403—1-404 

hyperbolic functions, 1-675 

IEEE floating-point rounding mode, 
1-157—1-158 

IEEE remainder, 1-114 

inverse hyperbolic functions, 1-26 

manipulating floating-point numbers, 
1-163—1-164 

modulo remainder, 1-141—1-143 

multiple precision integer arithmetic, 1-396 

natural logarithm of the gamma function, 
1-—322—1-323 

operations on floating-point exception flags, 
1-152—1-154 

operations on floating-point trap control, 
1-150—1-151 

rounding floating-point numbers to integers, 
1—141—1-143 

square root and cube root functions, 1-676 

testing for floating-point exceptions, 
1-155-—1-156 

trigonometric and inverse trigonometric 
functions, 1-673 


locking access to object class, using odm_lock 
subroutine, 1-504—1-505 

opening object class, using odm_open_class 
subroutine, 1-507 

preparing for application use, using 
odm_initialize subroutine, 1-503 

releasing a lock on a path name, using 
odm_unlock subroutine, 1-516 

removing object class from the filesystem, 
using odm_rm_class subroutine, 1-509 

removing objects, using odm_rm_obj 
subroutine, 1-510 

removing objects specified by their ID, using 
odm_rm_by_id subroutine, 1-598 


~ retrieving objects 


using odm_get_first subroutine, 
1-501—1-502 
using odm_get_next ssubroutine, 
1-501—1-502 
using odm_get_obj subroutine, 
1-501—1-502 
retrieving objects matching criteria, using 
odm_get_list subroutine, 1-499 
retrieving objects specified by their ID, using 
odm_get_by_id subroutine, 1-497—1-—498 
retrieving the class symbol structure, using 
odm_mount_class subroutine, 1-506 
returning error message String, using 
odm_err_msg subroutine, 1-495 
running a method, using odm_run_method 
subroutine, 1-511 
setting default permissions for object class, 
using odm_set_perms subroutine, 1-514 
setting the object class location default path, 
using odm_set_path subroutine, 1-513 
terminating session, using odm_terminate 
subroutine, 1-515 


object file 


close file, 1-301—1-—302 

compute symbol table entry index, 1-319 
manipulate line number entries, 1-306—1—307 
open file, 1-311—1-312 

read archive header, 1-300 

read file header, 1-303 

read section header, 1-315—1-316 


object, setting locale dependent conventions, 
localeconv subroutine, 1-333—1-335 
Object Data Manager 


read symbol table entry, 1-320 
retrieve symbol name, 1—-304—1~—305 


adding a new object, using 
odm_add_obj_ subroutine, 1-489—1-—490 

changing an object, using odm_change_obj 
subroutine, 1-491—1—492 

closing an object class, using odm_close_class 
subroutine, 1-493 

creating an object class, using 
odm_create_class subroutine, 1-494 

freeing memory, using odm_free_list 
subroutine, 1-496 


seek to line number entries, 1-308—1-—309 
seek to optional file header, 1-310 

seek to relocation entries, 1-313—1-—314 
seek to section, 1-317—1-318 

seek to symbol table, 1-321 


Object File Access Routine Library 


Idaclose subroutine, 1-301 
Idaopen subroutine, 1-311 
Idclose subroutine, 1-301 

Idfhread subroutine, 1-303 
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Idgetname subroutine, 1-304 
Idlinit subroutine, 1-306 
Idlitem subroutine, 1-306 
Idlread subroutine, 1-306 
Idiseek subroutine, 1-308 
Idniseek subroutine, 1-308 
Idnrseek subroutine, 1-313 
Idnshread subroutine, 1-315 
Idnsseek subroutine, 1-317 
ldohseek subroutine, 1-310 
Idopen subroutine, 1-311 
Idrseek subroutine, 1-313 
Idshread subroutine, 1-315 
Idsseek Subroutine, 1-317 
Idtbindex subroutine, 1-319 
Idtbread subroutine, 1-320 
Idtbseek subroutine, 1-321 
sgetl subroutine, 1-640 
sputl subroutine, 1-640 
object file access routine library, Idahread 
subroutine, 1-300 
object files, list loaded for current process, 
1-331—1-332 
obtain current specified display data from the 
presentation space, HCON programming, 2-40 
obtain value of user-defined variable for host, 
xgmon, 6-31 
odm,_free_list subroutine, 1-496 
odm_add_obj subroutine, 1-489—1-490 
odm_change_obj subroutine, 1-491—1-492 
odm_close_class subroutine, 1-493 
odm_create_class subroutine, 1-494 
odm_err_msg subroutine, 1-495 
odm_get_by_id subroutine, 1-497—1-498 
odm_get_first subroutine, 1-501—1-502 
odm_get_list subroutine, 1-499 
odm_get_next subroutine, 1-501—1-502 
odm_get_obj subroutine, 1~501—1-502 
odm_initialize subroutine, 1-503 
odm_lock subroutine, 1-504—1-—505 
odm_mount_class subroutine, 1-506 
odm_open_class subroutine, 1-507 
odm_rm_by_id subroutine, 1-508 
odm_rm_class subroutine, 1-509 
odm_rm_obj subroutine, 1-510 
odm_run_method subroutine, 1-511 
odm_set_path subroutine, 1-513 
odm_set_pers subroutine, 1-514 
odm_terminate subroutine, 1-515 
odm_unlock subroutine, 1-516 
omin subroutine, 1-396 
omout subroutine, 1-396 
open a file for reading or writing, 1-517—1-521 
open a GDLC device manager, 3-59 
open a stream, 1—-144—1-146 
open and rewind the network file, Sockets, 8-117 
open and rewind the protocols file, Sockets, 8-118 
open communications device handler, DLC, 3-12 
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open database for access, dbminit, 5-42 
open file, xgmon, 6-21 
open network host file, Sockets, 8-112 
open subroutine, 1-517—1-—521 
DLC, 3-59 
extended parameters for, DLC, 3-61 
open subroutine for generic SNA, SNA, 7-43 
open subroutine for SNA Services/6000, SNA, 7-41 
opendir subroutine, 1-522—1-524 
openlog subroutine, 1-734 
opens database for access, dobm_open, 5-39 
openx subroutine, 1-517—1-521 
output, binary, using fwrite subroutine, 
1-159—1-160 
output stream 
writing a string 
using fputws subroutine, 1-561 
using putws subroutine, 1-561 
writing null-terminated string 
using fputs subroutine, 1-558 
using puts subroutine, 1-558 


p 


packet for X.25 
indicating the type of, using x25_ receive 
subroutine, 9-33-—9-34 
receiving, using x25_receive subroutine, 
9-33—9-34 
paging space, find available, 1-547 
parameter blocks by ioctl operation, DLC, 3-32 
parameter list, variable-length parameter list, using 
varargs macros, 1—-788—1-—789 
parse_SNMP_packet subroutine, 6-56 
password 
generating, using newpass subroutine, 
1-460—1-461 
getting file entry 
using endpwent subroutine, 1-206—1—207 
using getpwent subroutine, 1-206—1-—207 
using getpwnam subroutine, 
1-—206—1-207 
using getpwuid subroutine, 1-206—1-207 
using setpwent subroutine, 1-206—1-207 
using setpwfile subroutine, 1—-206—1-207 
reading, using getpass subroutine, 1-197 
reading information, using getuserpw 
subroutine, 1-235—1-—236 
writing information, using setuserpw 
subroutine, 1-235—1-236 
password function, xgmon, 6-57 
passwords, encrypting . 
using crypt subroutine, 1-96—1-97 
using encrypt subroutine, 1-96—1-97 
using setkey subroutine, 1-96—1—97 
pathconf subroutine, 1-525—1-526 
pattern matching, compile a string into internal form, 
using re_comp subroutine, 1-568 


pause subroutine, 1-527 
pbrunnableprogram, 1-300, 1-301, 1-303, 1-304, 
1-306, 1-308, 1-310, 1-311, 1-313, 1-315, 
1-317, 1-319, 1-320, 1-321 
pclose subroutine, 1-528 
permit VGM to temporarily highlight display element, 
xgmon, 6-37 
perror subroutine, 1-529 
pfm_$cleanup library routine, NCS, 4-17 
pfm_$enable library routine, NCS, 4-19 
pfm_$enable_faults library routine, NCS, 4-20 
pfm_Sinhibit library routine, NCS, 4-21 
pfm_$inhibit_faults library routine, NCS, 4-22 
pfm_$init library routine, NCS, 4-23 
pfm_$reset_cleanup library routine, NCS, 4-24 
pfm_$rls_cleanup library routine, NCS, 4-25 
pfm_$signal library routine, NCS, 4-26 
phonic language, checking for support, using 
iMQueryLanguage subroutine, 1-273 
physical volume, querying for pertinent information, 
using lvm_querypv subroutine, 1-372—1-—374 
ping function, xgmon, 6-58 
pipe subroutine, 1-530 
place data under a key, dom_store, 5-40 
place data under a key, store, 5-65 
place long byte quantities in the byte stream, 
Sockets, 8-78 
place short byte quantities into the byte stream, 
Sockets, 8—80 
plock subroutine, 1-531—1-532 
plot subroutine family, 1-533 - 
pmap_getmaps subroutine, RPC, 5-56 
pmap_getport subroutine, RPC, 5-57 
pmap_rmtcall subroutine, RPC, 5-58 
pmap_set subroutine, RPC, 5—60 
pmap_unset subroutine, RPC, 5-61 
poll subroutine, 1-535—1-536 
popen subroutine, 1-537 
pow subroutine, 1—-129—1-131, 1-396 
presentation space, HCON programming 
obtain current specified display data, 2-40 
searching for character pattern in, 2-69 
searching for pattern in specified position after 
receiving host data, 2-89 
searching for pattern match in after receiving 
host data, 2-87 
searching for patterns in. See MATCHAT 
Statement 
searching for patterns in specified positon. See 
MATCH Statement 
setting g32_api structure to current cursor 
position in, 2-37 
print formatted output 
using printf subroutine, 1-538—1-543 
using wsprintf subroutine, 1-813 
printf subroutine, 1-538—1-543 
process . 
cleaning up the run-time environment, using 
kleenup subroutine, 1-296 


close a pipe, using pclose subroutine, 1-528 
control limits, using ulimit subroutine, 
1-772—1-773 
controlling system resources, 1-208—1-—210 
create a session and set group ID, using setsid 
subroutine, 1-633 
create new, using fork, vfork subroutines, 
1-147—1-149 
credentials, setting using setpcred subroutine, 
1-621—1-622 
execute a new program in the calling process, 
using exec subroutines, 1-120—1-126 
generate SIGIOT signal to terminate, using 
abort subroutine, 1—4 
get and set owner information, using usrinfo 
subroutine, 1-784—1-785 
getting alphanumeric user name, using cuserid 
subroutine, 1-106 
getting group IDs, using getgidx subroutine, 
_ 1-181 
getting the audit state, using auditproc 
subroutine, 1-44—1-—46 
initiate pipe, using popen subroutine, 1-537 
nice value, get or set, 1-204 
reading security credentials, using getpcred 
subroutine, 1-198—1-199 
return scheduling priority, with getpri 
subroutine, 1-203 
sending a signal to, using kill, killpg subroutine, 
1-294—1-295 
setting credentials, using getpenv subroutine, 
1-—200—1-201 
setting group IDs 
using setgid subroutine, 1-612—1-613 
using setgidx subroutine, 1-614—1-615 
using setrgid subroutine, 1-612—1-613 
setting scheduling priority to a constant, using 
setpri subroutine, 1-629—1-630 
setting the audit state, using auditproc 
subroutine, 1-44—1-—46 
setting the environment, using setpenv 
subroutine, 1-623—1-626 
suspend the calling process, 1-796—1-—-798 
suspending 
using nsleep subroutine, 1-487—1-—488 
using sleep subroutine, 1-487—1-488 
using usleep subroutine, 1-487—1-—488 
tracing execution of another, using ptrace 
subroutine, 1-549—1-554 
process accounting, enable and disable, using acct 
subroutine, 1-9—1-—10 
process group, setting ID 
using setpgid subroutine, 1-627—1-628 
using setpgrp subroutine, 1-627—1-—628 
processing keyboard event, using the IMProcess 
subroutine, 1-269—1-270 
processor, time used, reporting with clock 
subroutine, 1-84 
profil subroutine, 1-544—1—546 
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program address sampling, starting or stopping, 
using profil subroutine, 1-544—1-546 
Programmers Workbench Library 
regcmp subroutine, 1-578 
regex subroutine, 1-578 
provide SAP and link station correlators, DLC, 3-75 
psdanger subroutine, 1-547 
psignal subroutine, 1-548 
ptrace subroutine, 1-549—1-554 
putc subroutine, 1-555—1-—556 
putchar subroutine, 1-555—1-556 
putenv subroutine, 1-557 
putgrent subroutine, 1-182—1-—183 
putgroupattr subroutine, 1-184—1-187 
_putlong subroutine, Sockets, 8-78 
putpwent subroutine, 1—-206—1~-207 
puts subroutine, 1-558 
_putshort subroutine, Sockets, 8-80 
putuserattr subroutine, 1-229—1-234 
putw subroutine, 1—-555—1—-556 
putwc subroutine, 1-559—1-—560 
putwchar subroutine, 1-559—1-—560 
putws subroutine, 1-561 
PVC for X.25 
allocating for use by application, using 
x25_pvc_alloc subroutine, 9-31 
freeing, using x25_pvc_free subroutine, 9-32 
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qsort subroutine, 1-562 
query link station statistics, DLC, 3-48 
query operations, using IMloctl subroutine, 
1~—266—1-—267 
query service access point statstics, DLC, 3-47 
queue 
insert or remove an element, 1-282 
reading a message from, using msgxrcv 
subroutine, 1-450—1-—452 
R 


raise graphics window associated with VGM running 
program, xgmon, 6-59 
raise subroutine, 1-563 
raise_window function, xgmon, 6-59 
rand subroutine, 1-564—1-565 
random subroutine, 1-566—1-567 
rcmd subroutine, Sockets, 8-82 
re_comp subroutine, 1-568—1-569 
re_exec subroutine, 1-568—1-569 
read from a file, 1-570—1-573 
read function, xgmon, 6-60 
read next line in open file, xgmon, 6—60 
read pending data, DLC, 3-71 
read subroutine, 1-570—1-—573 
extended parameters for, DLC, 3-68 
read subroutine for generic SNA, SNA, 7-47 
read subroutine for SNA Services/6000, SNA, 7—45 
readdir subroutine, 1-522—1-524 
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readlink subroutine, 1-574—-1-575 
readv subroutine, 1-570—1-573 
readvx subroutine, 1-570—1-—573 
readx subroutine, 1-570—1-573 
DLC, 3-71 
readx subroutine for SNA Services/6000, SNA, 7—49 
real_type function, xgmon, 6-61 
realloc subroutine, 1-399—1—402 
reboot subroutine, 1—576—1—577 
receive a message from any socket, Sockets, 8-89 
receive host data, HCON programming 
locating beginning of pattern match in 
presentation space. See RECEIVE Statement 
searching presentation space for pattern 
match. See RECVAT Statement 
RECEIVE LAF statement, HCON programming, 
2-87 
receive message from AIX API application, HCON 
programming, 2-62 
receive message from connected sockets, Sockets, 
8-84 
receive message from host application, HCON 
programming, 2-65 
receive message from sockets, Sockets, 8-86 
receive network-specific data call, DLC, 3-66 
recv subroutine, Sockets, 8-84 
RECVAT LAF statement, HCON programming, 2—89 
recvfrom subroutine, Sockets, 8-86 
recvmsg subroutine, Sockets, 8-89 
registering interfaces with servers, 4—38 
registering objects and interfaces with Location 
Broker, 4-14 
registerrpc subroutine, RPC, 5-62 
regular—expression pattern matching, performing 
using advance subroutine, 1-87—1-90 
using compile subroutine, 1-87—1-90 
using NLregexp subroutine, 1-87—-1-90 
using regexp subroutine, 1-87—1-90 
using step subroutine, 1-87—1-—90 
reltimerid subroutine, 1-582 
remove a directory, 1-589—1-—590 
remove subroutine, 1-583 
removing entries from Location Broker database, 
4-16 
remque subroutine, 1-282 
rename display element, xgmon, 6-62 
rename subroutine, 1-584—1—586 
rename_dep function, xgmon, 6-62 
REPEAT-—UNTIL LAF statement, HCON 
programming, 2-90 
report NIS protocol error, ypprot_err, 5-147 
res_init subroutine, Sockets, 8-91 
res_mkquery subroutine, Sockets, 8-93 
res_send subroutine, Sockets, 8-96 
resabs subroutine, 1-190—1-192 
reset—indication packet for X.25, confirming receipt 
of, using x25_reset_confirm subroutine, 9-36 
resinc subroutine, 1-190—1-—192 


resource, get utilization information, 1-211—1-213 

resources, freeing, using IMFreeKeymap subroutine, 
1-261 

responses 

affirmative, NLyesno subroutine, 1-486 
negative, NLyesno subroutine, 1-486 

restart system, using reboot subroutine, 
1-576—1-577 

restimer subroutine, 1-220—1-221 

retrieve a socket with a priviledged address, 
Sockets, 8-100 

retrieves a network host entry, Sockets, 8-28 

retrieves long byte quantities, Sockets, 8-31 

retrieves short byte quantities, Sockets, 8—52 

return a device descriptor structure, DLC, 3-57 

return a pointer to an error String, yperr_string, 
5-146 

return asynchronous exception noticifications, DLC, 
3-52 

return current address of host, xgmon, 6-30 

return current system time, xgmon, 6-80 

return first key in database, firstkey, 5-45 
return first key value pair, yp_first, 5-135 

~ return font height in graphics window associated with 
VGM, xgmon, 6-19 

return font width in graphics window associated with 
VGM, xgmon, 6-20 

return height of graphics window associated with 
VGM, xgmon, 6-82 

return information about display element, xgmon, 
6-10 

return integer ASCII value of first character of string, 
xgmon, 6-5 

return integer value represented by text characters in 
string, xgmon, 6-36, 6-81 

return IP address of host, xgmon, 6—40 

return length of string, xgmon, 6-78 

return list of display elements grouped under node, 
xgmon, 6-23 

return machine name of NIS master server, 
yp_master, 5-138 

return MIB numeric—format variable name of MIB 
text-format variable name, xgmon, 6-76 

return name of MIB variable, SNMP, 6-46 

return next key in database, nextkey, 5-55 

return number indicating actual MIB type of MIB 
variable name or instance ID, xgmon, 6-61 

return number indicating base type of MIB variable 
name or instance ID, xgmon, 6-6 

return number of free words in data segment of 
VGM, xgmon, 6-84 

return of data and correlators structure, DLC, 3-68 

return order number of NIS map, yp_order, 5-142 

return pointer to array of strings representing display 
element names, xgmon, 6-53 

return receive data, DLC, 3-14 

return SNMP community name of host, xgmon, 6-57 

return status information of the logical path, HCON 
programming, 2-43 


return string of text characters representing decimal 
value of integer, xgmon, 6-55 
return string representing IP address, xgmon, 6-12 
return text name of host, SNMP, 6-42 
return text name of host, xgmon, 6-39 
return text name of MIB variable, SNMP, 6-27 
return the Internet address of host, SNMP, 6-43 
return value indicating base type of MIB variable, 
SNMP, 6-24 
return value indicating variable type of MIB variable, 
SNMP, 6-28 
return values found in NIS map, 5-140 
return width of graphics window associated with 
VGM, xgmon, 6-83 
returns first key in database, dobm_firstkey, 5-37 
returns next key in database, dbm_next, 5-38 
reuse_mem function, xgmon, 6-63 
revoke subroutine, 1-587—-1—588 
revoking file access, using frevoke subroutine, 
1-161—1-162 
rewind subroutine, 1-167—1-168 
rewinddir subroutine, 1-522—1-524 
rexec subroutine, Sockets, 8-98 
right function, xgmon, 6-64 
rindex subroutine, 1-717 
rint subroutine, 1-141—1-143 
rmdir subroutine, 1-589—-1—590 
root directory, changing, using chroot subroutine, 
1-74—1-75 
RPC macros 
auth_destroy, 5-6 
clnt_call, 5-14 
clnt_control, 5-16 
clnt_destroy, 5-19 
clnt_freeres, 5-20 
clnt_geterr, 5-21 
svc_destroy, 5-66 
svc_freeargs, 5-67 
svc_getargs, 5-68 
svc_getcaller, 5-69 
RPC subroutines 
authdes_create, 5-3 
authdes_getucred, 5—5 
authnone_create, 5—7 
authunix_create, 5-8 
authunix_create_default, 5-9 
callrpc, 5-10 
clnt_broadcast, 5-12 
cint_create, 5-18 
clnt_pcreateerror, 5—22 
clnt_perrno, 5-23 
cilnt_perror, 5—24 
cint_spcreateerror, 5-25 
clnt_sperrno, 5-26 
clnt_sperror, 5-28 
clntraw_create, 5—29 
clnttcp_create, 5-30 
clntudp_create, 5-32 
get_myaddress, 5~46 
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getnetname, 5-47 
host2netname, 5-48 
key_decryptsession, 5-49 
key_encryptsession, 5-50 
key_gendes, 5-51 
key_setsecret, 5-52 
netname2host, 5-53 
netname2user, 5-54 
pmap_getmaps, 5-56 
pmap_getport, 5-57 
pmap_rmtcall, 5-58 
-pmap_set, 5-60 
pmap_unset, 5-61 
registerrpc, 5-62 
rtime, 5-64 
svc_getreqset, 5-70 
svc_register, 5-71 
svc_run, 5-73 
svc_sendreply, 5-74 
svc_unregister, 5—75 
svcerr_auth, 5-76 
svcerr_decode, 5-77 
svcerr_noproc, 5-78 
svcerr_noprog, 5—79 
svcerr_progvers, 5-80 
svcerr_systemerr, 5-81 
svcerr_weakauth, 5-82 
svcfd_create, 5-83 
svcraw_create, 5-84 
svctcp_create, 5-85 
svcudp_create, 5-86 
user2netname, 5-87 
xdr_accepted_reply, 5-88 
xdr_authunix_parms, 5-90 
xdr_callihdr, 5-92 
xdr_calimsg, 5-93 
xdr_opaque_auth, 5-105 
xdr_pmap, 5-106 
xdr_pmaplist, 5-107 
xdr_rejected_reply, 5-110 
xdr_replymsg, 5-111 
xprt_register, 5-129 
xprt_unregister, 5-130 
roc_$alloc_handle library routine, NCS, 4-27 
rpoc_$bind library routine, NCS, 4-28 
roc_$clear_binding library routine, NCS, 4-29 
rpc_$clear_server_binding library routine, NCS, 
4-30 
rpc_$dup_handle library routine, NCS, 4-31 
rpc_$free_handle library routine, NCS, 4-32 
rpc_$ing_binding library routine, NCS, 4-33 
rpc_$inq_object library routine, NCS, 4-34 
rpc_$listen library routine, NCS, 4—35 
rpc_$name_to_sockaddr library routine, NCS, 4-36 
rpc_$register library routine, NCS, 4-38 
rpc_$set_binding library routine, NCS, 4-40 
rpc_$sockaddr_to_name library routine, NCS, 4—41 
rpc_$unregister library routine, NCS, 4-42 
rpc_$use_family library routine, NCS, 4-43 
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rpc_$use_family_wk library routine, NCS, 4—45 
rpow subroutine, 1-396 
rresvport subroutine, Sockets, 8-100 
rtime subroutine, RPC, 5-64 
Run-time Services Library 
trcon subroutine, 1-761 
trestart subroutine, 1-762 
trcstop subroutine, 1-763 
runtime resolution of deferred symbols, 1-329 
ruserok subroutine, Sockets, 8-102 


S 


SAP enable a result extension, DLC, 3-55 
save and restore execution context, 1-617—1-618 
save_SNMP_trap subroutine, 6-65 
save_SNMP_var subroutine, 6-67 
sbrk subroutine, 1-52—1-53 
scalb subroutine, 1-94—1—95 
scan directory contents, 1-591 
scandir subroutine, 1-591—1-592 
scanf subroutine, 1-593—1-597 
sdiv subroutine, 1-396 
search 
binary search, 1-54 
binary tree search, 1-766 
linear search and update, 1-339 
manage hash tables, 1-246 
walk a file tree, 1-172 
search for a default domain name and Internet 
address, Sockets, 8-91 
search for character pattern in presentation space, 
HCON programming, 2-69 
search for pattern match, HCON programming 
in presentation space, 2-84 
in specified position of presentation space, 
2-85 
search for value associated with key, yo_ match, 
5-139 
search source string for substring, xgmon, 6-79 
searches for an expanded domain name, Sockets, 
8-15 
Security Library 
acl_chg subroutine, 1-11—1-13 
acl_fchg subroutine, 1-11—1-13 
acl_fget subroutine, 1-14—1-15 
acl_fput subroutine, 1-16—1-18 
acl_fset subroutine, 1-19—1-21 
acl_get subroutine, 1-14—1-15 
acl_put subroutine, 1-16—1-—18 
acl_set subroutine, 1-19—1-21 
auditpack subroutine, 1-42—-1—43 
auditread subroutine, 1-47 
auditwrite subroutine, 1-48 
ckuseracct subroutine, 1-80—1-81 
ckuserID subroutine, 1-78—1-—79 
endpwdb subroutine, 1-631—1-—632 
enduserdb subroutine, 1-638—1-639 
getgroupattr subroutine, 1-184—1—187 


getpcred subroutine, 1-198 
getpenv Subroutine, 1-200 
getuserattr subroutine, 1-229—1-—234 
getuserpw subroutine, 1-235—1-236 
IDtogroup subroutine, 1-184—1-—187 
|Dtouser subroutine, 1-229—1~—234 
newpass subroutine, 1-460—1-—461 
nextgroup subroutine, 1-184—1-187 
nextuser subroutine, 1-229—1-234 
putuser subroutine, 1-229—1-234 
setpcred subroutine, 1-621 
setpenv subroutine, 1-623 
setpwdb subroutine, 1-631— 1-632 
setuserdb subroutine, 1-638—1-639 
setuserpw subroutine, 1-235—1-—236 
seed48 subroutine, 1-111—1-113 | 
seekdir subroutine, 1-522—1-524 
SELECT LAF statement, HCON programming, 2-91 
select receive data or exception conditions, DLC, 
3-16 
select subroutine, 1-598—1-600 
DLC, 3-73 
select subroutine for generic SNA, SNA, 7-56 
select subroutine for SNA Services/6000, SNA, 7-53 
semaphore, returning semaphore identifier, using 
semget subroutine, 1-605—1—-607 
semaphore operations, controlling, using semctl 
subroutine, 1-601—1-604 
semapore operations, using semop subroutine, 
1-608—1-—609 
semct! subroutine, 1-601—1-604 
semget subroutine, 1-605—1—-607 
semop subroutine, 1-608—1—-609 
send a message to a host application, HCON 
programming, 2-80 
send a message using a socket message structure, 
Sockets, 8-106 
send a query to a name server, Sockets, 8-96 
send an ICMP ECHO request to host, xgmon, 6-58 
send application data, DLC, 3-77 
send kernel data, DLC, 3-26 
SEND LAF statement, HCON programming, 2-93 
send message from a connected socket, Sockets, 
8-104 
send message to AIX API application, HCON 
programming, 2-78 
send messages through a socket, Sockets, 8-108 
send query to and await response from SNMP agent, 
SNMP, 6-69 
send string of keys to emulator and host, HCON 
programming, 2-93 
send subroutine, Sockets, 8-104 
send_recv_SNMP_packet subroutine, 6-69 
sendmsg subroutine, Sockets, 8-106 
sends key strokes to the terminal emulator, HCON 
programming, 2-74 
sendto subroutine, Sockets, 8-108 
separate local Internet addresses, Sockets, 8-64 


separate network Internet addresses into network 
number and local address, Sockets, 8-68 
servers 
clearing handle bindings, 4-30 
registering interfaces, 4-38 
session, HCON programming 
attach to, 2-49 
attaching to (extended open), 2-55 
detach AIX API program from, 2-21 
set file access times, 1-786—1-—787 
set file modification times, 1-786—1-—787 
set 932_api structure to the current cursor position, 
HCON programming, 2-37 
set socket options, Sockets, 8-120 
set the name of the current domain, Sockets, 8-111 - 
set the name of the current host, Sockets, 8-115 
set the unique identifier of the current host, Sockets, 
8-114 
set user—defined environment variable for host, 
xgmon, 6-73 
set_element_mask function, xgmon, 6-71 
setbuf subroutrine, 1-610—1-611 
setbuffer subroutine, 1-610—1-611 
setdomainname subroutine, Sockets, 8—111 
setegid subroutine, 1-612—1-613 
setenv function, xgmon, 6-73 
seteuid subroutine, 1-634—1-635 
setgid subroutine, 1-612—1-613 
setgidx subroutine, 1-614—1-615 
setgrent subroutine, 1-182—1-183 
setgroups subroutine, 1-616 
sethostent subroutine, Sockets, 8-112 
sethostid subroutine, Sockets, 8-114 
sethostname subroutine, Sockets, 8-115 
setitimer subroutine, 1-190—1-—192 
setimp subroutine, 1-617—1-618 
setkey subroutine, 1-96—1-97 
setlinebuf subroutine, 1-610—1-611 
setlocale subroutine, 1-619—1-620 
setlogmask subroutine, 1-734 
setnetent subroutine, Sockets, 8—117 
setpcred subroutine, 1-621—1-—622 
setpenv subroutine, 1-623—1-626 
setpgid subroutine, 1-627—1-—628 
setpgrp subroutine, 1-627—1-628 
setpri subroutine, 1-629—1-630 
setpriority subroutine, 1-204—1-205 
setprotoent subroutine, Sockets, 8-118 
setpwdb subroutine,1—631 
setpwent subroutine, 1—206—1-207 
setregid subroutine, 1-612—1-613 
setreuid subroutine, 1-634—1-635 
setrgid subroutine, 1-612—1-613 
setrlimit subroutine, 1-208—1—210 
setruid subroutine, 1-634—1-635 
setservent subroutine, Sockets, 8—119 
setsid subroutine, 1-633 
setsockopt subroutine, Sockets, 8—120 
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setstate subroutine, 1-566—1-567 
settimeofday subroutine, 1-218—1-219 
settimer subroutine, 1-220—1-221 
settyent subroutine, 1—224—1-—225 
setuid subroutine, 1-634—1-635 
setuidx subroutine, 1-636—1-637 
setuserdb subroutine, 1-638—1-—639 
setuserpw subroutine, 1-235—1~236 
setutent subroutine, 1-237—1-239 
setvbuf subroutine, 1~610—1-—611 
setvfsent subroutine, 1-240—1-241 
setwdb subroutine, 1-631—1-632 
sgetl subroutine, 1-640 
shell command, running, using system subroutine, 
1-737 
shmat subroutine, 1-641—1-643 
shmetl subroutine, 1-644—1-646 
shmat subroutine, 1-647 
shmget subroutine, 1-648—1-—650 
shorten a file, using truncate, ftruncate subroutines, 
1-764—1-765 
shut down socket send and receive operations, 
Sockets, 8-124 
shutdown subroutine, Sockets, 8-124 
sigaction subroutine, 1-651—1-657 
sigaddset subroutine, 1-658—1-659 
sigblock subroutine, 1-662—1—664 
sigdelset subroutine, 1-658—1—659 
sigemptyset subroutine, 1-658—1-—659 
sigfillset subroutine, 1-658—1-—659 
sighold subroutine, 1~665— 1-667 
sigignore subroutine, 1-665—1-667 
siginterrupt subroutine, 1-660 
sigismember subroutine, 1-658—1-—-659 
siglongjmp subroutine, 1-668 
signal 
change restart behavior, using siginterrupt 
subroutine, 1-660 
enhance signal facility and provide signal 
management, 1-665 
get and set stack context, using the sigstack 
subroutine, 1-669—1-670 
print system signal messages, using psignal 
subroutine, 1-548 
restore saved signal mask, using siglongjmp 
subroutine, 1-668 
save current signal mask, using sigsetimp 
subroutine, 1-668 
save current stack context, using sigsetijmp 
subroutine, 1-668 
send to the executing program, using raise 
subroutine, 1-563 
store set of signals blocked from delivery, using 
sigpending subroutine, 1-661 
signal facility, implementing 
using gsignal subroutine, 1-704—1-705 
using ssignal subroutine, 1-704—1-705 
signal handling, specify action to be taken, 
1-651—1-657 
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signal mask 
examine or change, using sigoprocmask 
subroutine, 1-662 
setting current, using sigprocmask subroutine, 
1-662 
signal masks, manipulating 
using sigaddset subroutine, 1-658—1~-659 
using sigdelset subroutine, 1-658—1-659 
using sigemptyset subroutine, 1-658—1-659 
using sigfillset subroutine, 1-658—1-659 
using sigismember subroutine, 1-658—1-—659 
signal subroutine, 1-651—1—657 
signals 
adding individual signal, using sigaddset 
subroutine, 1-658 
deleting individual signals, sigdelset subroutine, 
1-658 
initializing signal set 
using sigemptyset, 1-658 
using sigfillset, 1-658 
specifying member of signal set, using 
sigismember subroutine, 1-658 
suspending execution of process, using 
sigsuspend subroutine, 1-671 
sigpause subroutine, 1-671—1-672 
sigpending subroutine, 1-661 
sigpromask subroutine, 1-662—1-—664 
sigrelse subroutine, 1-665—1—667 
sigset subroutine, 1-665—1-—667 
sigsetimp subroutine, 1-668 
sigsetmask subroutine, 1-662—1-664 
sigsuspend subroutine, 1-671—1-672 
sigtack subroutine, 1-669—1-670 
sigvec subroutine, 1-651—1-657 
sin subroutine, 1-673—1-—674 
sinh subroutine, 1-675 
sjtojis subroutine, 1-292—-1~293 
sjtouj subroutine, 1-292—1-293 
skips over a compressed domain name, Sockets, 
8-17 
sleep subroutine, 1-487—1-—488 
SNA subroutines 
generic 
close, 7-5 
ioctl, 7-15 
open, 7—43 
read, 7-47 
select, 7-56 
write, 7-83 
luQapi, 7-17 
luOclosep, 7-20 
luOcloses, 7-21 
luOctlp, 7-22 
luOctls, 7-24 
luOopenp, 7~26 
luOopens, 7-27 
luOreadp, 7-28 
luOreads, 7-29 
luOwritep, 7-30 


luOwrites, 7-32 
nm_close, 7-34 
nm_open, 7-35 
nm_receive, 7-36 
nm_send, 7-38 
nm_status, 7—40 
SNA Services/6000 
close, 7-3 
ioctl, 7-6 
open, 7-41 
read, 7-45 
readx, 7-49 
select, 7-53 
write, 7-81 
writex, 7-85 
snacise, 7-59 
snact!, 7-60 
snadeal, 7-67 
snalloc, 7-70 
snaopen, 7-73 
snaread, 7-75 
snawrit, 7-78 
snaclise subroutine, SNA, 7-59 
snactl subroutine, SNA, 7-60 
snadeal subroutine, SNA, 7-67 
snalloc subroutine, SNA, 7—70 
snaopen subroutine, SNA, 7-73 
snaread subroutine, SNA, 7—75 
snawrit subroutine, SNA, 7-78 
SNMP, SNMP Manager, intrinsic functions 
database operations 
base_type, 6-6 
getenv, 6-31 
get_MIB_group, 6-25 
gw_var, 6-34 
real_type, 6-61 
setenv, 6-73 
snmp_var, 6-76 
file 1/O 
close, 6-7 
fopen, 6-21 
read, 6—60 
formatted output 
num, 6-55 
sprintf, 6-77 
graphics functions 
dep_info, 6-10 
draw_line, 6-13 
draw_string, 6-14 
font_height, 6-19 
font_width, 6-20 
get_deps, 6—23 
group_dep, 6-32 
highlight_dep, 6-37 
make_dep, 6—47 
make_link, 6-48 
move_dep, 6-52 
new_deps, 6-53 
raise_window, 6-59 


rename_dep, 6-62 
set_element_mask, 6-71 
window_height, 6-82 
window_width, 6-83 
host information 
dotaddr, 6-12 
get_primary, 6-30 
hostname, 6-39 
ipaddr, 6-40 
next_alternate, 6-54 
password, 6-57 
ping, 6-58 
string manipulation 
ascii, 6-5 
hexval, 6-36 
left, 6-41 
mid, 6-51 
right, 6-64 
strien, 6-78 
substr, 6-79 
val, 6-81 
virtual G machine (VGM) control 
aix_exec, 6-3 
alloc, 6-4 
ctime, 6-9 
exec, 6-16 
flush_trap, 6-18 
reuse_mem, 6-63 
time, 6-80 
words free, 6-84 


SNMP API 


create_SNMP_port subroutine, 6-8 
extract_SNMP_name subroutine, 6-17 
get_MIB_base_type subroutine, 6-24 
get_MIB_name subroutine, 6-27 
get_MIB_variable_type subroutine, 6-28 
lookup_addr subroutine, 6—42 
lookup_host subroutine, 6-43 
lookup_SNMP_group subroutine, 6-44 
lookup_SNMP_name subroutine, 6-46 
make_SNMP_request subroutine, 6—49 
parse_SNMP_packet subroutine, 6-56 
save_SNMP_trap subroutine, 6-65 
save_SNMP_var subroutine, 6-67 
send_recv_SNMP_packet subroutine, 6-69 
SNMP_errormsg array, 6-75 


SNMP_errormsg array, 6-75 
snmp_var function, xgmon, 6-76 
socket subroutine, Sockets, 8-126 
socketpair subroutine, Sockets, 8-129 
sockets 


converting address to host name, 4-41 
converting host name to address, 4-36 
creating specific address family sockets, 4—43 
creating with well-known port, 4—45 


Sockets subroutines 


accept, 8-3 
bind, 8-5 
connect, 8-8 
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dn_comp, 8-11 
dn_expand, 8-13 
dn_find, 8-15 
dn_skipname, 8-17 
endhostent, 8-19 
endnetent, 8-20 
endprotoent, 8—21 
endservent, 8-22 
getdomainname, 8-23 
gethostbyadar, 8-24 
gethostbyname, 8-26 
gethostent, 8-28 
gethostid, 8-29 
gethostname, 8-30 
_getlong, 8-31 
getnetbyaddr, 8-33 
getnetbyname, 8-35 
getnetent, 8-37 
getpeername, 8-38 
getprotobyname, 8-40 
getprotobynumber, 8—42 
getprotoent, 8-44 
getservbyname, 8-46 
getservbyport, 8-48 
getservent, 8-50 
_getshort, 8-52 
getsockname, 8-54 
getsockopt, 8-56 
hton!, 8-60 

htons, 8-61 
inet_addr, 8-62 
inet_Inaof, 8-64 
inet_makeaddr, 8—66 
inet_netof, 8-68 
inet_network, 8—70 
inet_ntoa, 8-72 
listen, 8-74 

ntohl, 8—76 

ntohs, 8-77 
_putlong, 8-78 
_putshort, 8-80 
remd, 8-82 

recv, 8-84 

recvfrom, 8-86 
recvmsg, 8-89 
res_init, 8-91 
res_mkquery, 8-93 
res_send, 8-96 
rexec, 8-98 
rresvport, 8—100 
ruserok, 8-102 

send, 8-104 
sendmsg, 8-106 
sendto, 8-108 
setdomainname, 8-111 
sethostent, 8-112 
sethostid, 8-114 
sethostname, 8-115 
setnetent, 8-117 
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setprotoent, 8-118 
setservent, 8-119 
setsockopt, 8-120 
shutdown, 8-124 
socket, 8-126 
socketpair, 8-129 
sort a table of data in place, 1-562 
sort directory contents, 1-591 
specify data sent, DLC, 3-18 
specify special file names, DLC, 3-24 
sprintf function, xgmon, 6-77 
sprintf subroutine, 1-538—1—-543 
sput! subroutine, 1-640 
sqrt subroutine, 1-676 
error code listed, 1-676 
srand subroutine, 1-564—1—565 
srand48 subroutine, 1-111—1-—113 
srandom subroutine, 1-566—1-—567 
SRC error message, retrieve, using src_err_msg 
subroutine, 1-677 
SRC status, get line header, using srcstathdr 
subroutine, 1-696 
SRC status code, get text representation, using 
srcstattxt subroutine, 1-697 
SRC subsystem, replying to the client process, using 
srcsrpy subroutine, 1-684—1-688 
srcrrqs subroutine, 1-678—1-—679 
srcsbuf subroutine, 1-680—1-—-683 
srcsrpy subroutine, 1-684—1—688 
srcsrqt subroutine, 1-689—1-692 
srcstat subroutine, 1-693—1-—695 
srcstathdr subroutine, 1-696 
srestattxt subroutine, 1-697 
srcstop subroutine, 1-698—1-—700 
srcstrt subroutine, 1-701—1-703 
sscanf subroutine, 1-593—1—597 
ssignal subroutine, 1-704—1—705 
Security Library, getgroupattr subroutine, 1-616 
start a link station, DLC, 3-36 
start a link station’s result extension, DLC, 3-55 
start interaction with AIX API, HCON programming, 
2-15 
START LAF statement, HCON programming, 2-94 
stat subroutine, 1-711—1-—714 
statacl subroutine, 1-706—1-708 
statfs subroutine, 1-709—1-—710 
status, file, 1-711 
statx subroutine, 1-711—1-714 
step subroutine, 1~87—1-—90 
stime subroutine, 1—220—1-221 
store retrieved SNMP data, SNMP, 6-67 
store SNMP error messages, SNMP, 6-75 
store SNMP trap data, SNMP, 6-65 
store subroutine, 5-65 
strcat subroutine, 1-716 
strchr subroutine, 1-716 
strcmp subroutine, 1-716 
strcoll subroutine, 1-716 
strcpy subroutine, 1-716 


strcspn subroutine, 1-716 
strdup subroutine, 1-717 
stream 
write buffered data and close, using fclose 
subroutine, 1-134 
write buffered data and leave open, using fflush 
subroutine, 1-134 
writing a character 
using fput subroutine, 1-555—1-—556 
using fputwc subroutine, 1-559—1-560 
using putc subroutine, 1-555—1-556 
using putchar subroutine, 1-555—1-—556 
using putwc subroutine, 1-559—1-—560 
using putwchar subroutine, 1-559—1—-560 
writing a word, using putw subroutine, 
1-555—1-556 
strerror subroutine, 1-715 
strftime subroutine, 1-475—1-—477 
string 
checking the argument, using re_exec 
subroutine, 1-568 
collation value, using the strncollen subroutine, 
1-720 
converting on 8—bit processing codes, 
1—292—1-293 
locating first occurence of a character, using 
wespbrk subroutine, 1-803 
performing operations on type wchar, using 
wstring subroutines, 1-816—1-—818 
rebinding to specified KeySymbol and State 
pair, using the IMRebindCode subroutine, 
1-275 
variable length 
comparing, bcmp subroutine, 1-49 
copying values, bcopy subroutine, 1-49 
returning index of bit, ffs subroutine, 1-49 
zeroing out string, bzero subroutine, 1-49 
strings 
containing code points, using NLstring 
subroutines, 1-472 
perform operations, using string subroutines, 
1-716 
performing operations on type NLchar, using 
NCstring subroutines, 1-456—1-459 
strlen function, xgmon, 6-78 
strlen subroutine, 1-716 
strncat subroutine, 1-716 
strncmp subroutine, 1-716 
strncollen subroutine, 1-720 
strncpy subroutine, 1-716 
strpbrk subroutine, 1-716 
strrchr subroutine, 1-716 
strspn subroutine, 1-716 
strstr subroutine, 1-717 
strtod subroutine, 1-28—1-29 
strtof subroutine, 1-28—1-29 
strtok subroutine, 1-717 
strtol subroutine, 1-721—1-722 
strtoul subroutine, 1-721—1—-722 


strtows subroutine, 1-463 
strxfrm subroutine, 1-716 
stty subroutine, 1-723 
subroutine, semct! subroutine, 1-601—1-604 
substr function, xgmon, 6-79 
subsystem 
adding a record to object class, using addssys 
subroutine, 1-22—1-23 
getting short status, using srcstat subroutine, 
1-693—1-695 
getting status, using srcsbuf subroutine, 
1-680—1-683 
initialize SRCsubsys structure, using defssys 
subroutine, 1-107—1-108 
read a record, using getsubsvr subroutine, 
1-216—1-217 
reading record, using chssys subroutine, 
1—76—1-77 
reading the record, using getssys Subroutine, 
1-215 
removing subsystem objects, using delssys 
subroutine, 1-109 
sending a request to, using srcsrqt subroutine, 
1-689—1-692 
starting, using srcstrt subroutine, 
1-701—1-703 
stopping, using srcstop subroutine, 
1-698— 1-700 
subsystem reply information, using srcrrqs 
subroutine, 1-678—1-679 
svc_destroy macro, RPC, 5-66 
svc_freeargs macro, RPC, 5-67 
svc_getargs macro, RPC, 5-68 
svc_getcaller macro, RPC, 5-69 
svc_getreqset subroutine, RPC, 5—70 
svc_register subroutine, RPC, 5-71 
svc_run subroutine, RPC, 5-73 
svc_sendreply subroutine, RPC, 5—74 
svc_unregister subroutine, RPC, 5-75 
svcerr_auth subroutine, RPC, 5-76 
svcerr_decode subroutine, RPC, 5-77 
svcerr_noproc subroutine, RPC, 5-78 
sveerr_noprog subroutine, RPC, 5—79 
svcerr_progvers subroutine, RPC, 5-80 
svcerr_systemerr subroutine, RPC, 5-81 
svcerr_weakauth subroutine, RPC, 5-82 
svcfd_create subroutine, RPC, 5-83 
svcraw_create subroutine, RPC, 5-84 
svctcp_create subroutine, RPC, 5-85 
svcudp_create subroutine, RPC, 5-86 
swab subroutine, 1-724 
swapon command, 1-725 
swapaqry subroutine, 1-726 
symbolic link, reading contents of, with readlink 
subroutine, 1-574 
symlink subroutine, 1-728 
sync subroutine, 1-731 
SYS_CFGDD operation, 10-3 
SYS_CFGKMOD operation, 10-5 
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SYS_GETPARMS operation, 10-9 
SYS_KLOAD operation, 10-10 
SYS_KULOAD operation, 10-13 
SYS_QDVSW operation, 10-15 
SYS_QUERYLOAD operation, 10-18 
SYS_SETPARMS operation, 10-20 
sys_Siglist vector, 1-548 
SYS_SINGLELOAD operation, 10-22 
sysconf subroutine, 1-732—1-733 
sysconfig subroutine, 10-7 
operations 
SYS_CFGDD, 10-3 
SYS_CFGKMOD, 10-5 
SYS_GETPARMS, 10-9 
SYS_KLOAD, 10-10 
SYS_KULOAD, 10-13 
SYS_QDVSW, 10-15 
SYS_QUERYLOAD, 10-18 
SYS_SETPARMS, 10-20 
SYS_SINGLELOAD, 10-22 
syslog subroutine, 1-734 
system, getting the name, using the uname, unamex 
subroutine, 1-777—1-—778 
system data object, setting the auditing mode, 
1-39—1-41 
system limit, find current value, 1-732—1-—733 
System Resource Controller Library 
addssys subroutine, 1-22—1-23 
chssys subroutine, 1-76—1-77 
defssys subroutine, 1-107—1-108 
delssys subroutine, 1-109 
getssys subroutine, 1-215 
getsubsvr subroutine, 1-216—1-—217 
src_err_msg subroutine, 1-677 
srcrrqs subroutine, 1-678—1-679 
srcsbuf subroutine, 1-680—1-683 
srcsrpy subroutine, 1-684—1-688 
srcsrqt subroutine, 1-689—1-692 
srcstat subroutine, 1-693—1-695 
srcstathdr subroutine, 1-696 
srcstattxt subroutine, 1-697 
srcstop subroutine, 1-698—1-700 
srcstrt subroutine, 1-701—1-—703 
system subroutine, 1-737 
System V Math Library 
acos subroutine, 1-673—1-674 
acosh subroutine, 1-26 
asin subroutine, 1-673—1-674 
asinh subroutine, 1-26 
atan subroutine, 1-673—1-674 
atan2 subroutine, 1-673—1-674 
atanh subroutine, 1-26 
cabs subroutine, 1-248—1-249 
cbrt subroutine, 1-676 
ceil subroutine, 1-141—1-143 
class subroutine, 1-82 
copysign subroutine, 1-94—1-95 
cos subroutine, 1-673—1-674 
cosh subroutine, 1-675 
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drem subroutine, 1-114 

erf subroutine, 1-118 

erfc subroutine, 1-118 

exp subroutine, 1-129—1-131 
expm1 subroutine, 1-129—1-131 
fabs subroutine, 1-141—1-143 
finite subroutine, 1-82 

floor subroutine, 1-141—1-143 
fmod subroutine, 1-141—1-143 
gamma subroutine, 1-322—1-323 
hypot subroutine, 1-248—1-—249 
ilogb subroutine, 1-94—1-95 
isnan subroutine, 1-82 

itrtunc subroutine, 1-141—1-143 
jO subroutine, 1-50—1-51 

j1 subroutine, 1-50—1-51 

jn subroutine, 1-50—1-—51 
Igamma subroutine, 1~322—1-323 
log subroutine, 1-129—1-131 
log10 subroutine, 1-129—1-131 
logip subroutine, 1-129—1-131 
logb subroutine, 1-94—1-95 
matherr subroutine, 1-403—1-404 
nearest subroutine, 1-141—1-143 
nextafter subroutine, 1-94—1-95 
pow subroutine, 1-129—1-131 
rint subroutine, 1-141—-1-143 
scalb subroutine, 1-94—-1-95 

sin subroutine, 1-673—1-674 
sinh subroutine, 1-675 

sqrt subroutine, 1-676 

tan subroutine, 1-673—1-674 
tanh subroutine, 1-675 

trunc subroutine, 1-141—-1-143 
uitrunc subroutine, 1-141—1-143 
unordered subroutine, 1-82 

yO subroutine, 1-50—1-51 

y1 subroutine, 1-50—1-—51 

yn subroutine, 1-50—1-—51 


T 


tahn subroutine, 1-675 
tan subroutine, 1-673—1-674 
tcdrain subroutine, 1-740 
tcflow subroutine, 1-741 
tcflush subroutine, 1-742 
tcgetattr subroutine, 1-744 
tcgetpgrp subroutine, 1-745 
tcsendbreak subroutine, 1-746 
tcsetattr subroutine, 1-748—1-—749 
tcsetpgrp subroutine, 1-750 
telldir subroutine, 1-522—1-524 
tempnam subroutine, 1-754—1-755 
temporary file, generate file name, 1-754—1-—755 
termdef subroutine, 1-751—1-752 
terminal 
determine if a device is a terminal, using isatty 
subroutine, 1-770 


getting foreground group ID, using tcgetpgrp 
subroutine, 1-745 
getting the name, using ttyname subroutine, 
1-770 
line control functions 
using tcdrain subroutine, 1-740 
using tcflow subroutine, 1-741 
using tcflush subroutine, 1-742 
using tcgetattr subroutine, 1-744 
using tcsendbreak subroutine, 1-746 
using tcsetattr subroutine, 1-748 
query terminal characteristics, using termdef 
subroutine, 1-751 
setting foreground group ID, using tcsetpgrp 
subroutine, 1-750 
terminate a process, using exit, exit, atexit 
subroutines, 1-127—1-128 
terminate execution of LAF script, HCON 
programming, 2-9 
terminate interaction with an AIX API, HCON 
programming, 2-27 
test a remote station link for a link station, DLC, 3-41 
test fpr conditional execution of LAF script, HCON 
programming, two-way alternative test, 2-83 
time 
formatting, using NLstrtime subroutine, 
1-—475—1-477 
getting, using gettimeofday subroutine, 
1-218—1-219 
setting, using settimeofday subroutine, 
1—218—1-219 
time function, xgmon, 6—80 
time structure, setting from string data, using 
NLtmtime subroutine, 1-478—1-—480 
time subroutine, 1-220—1-221 
timer, system—wide 
getting using gettimer subroutine, 
1-220—1-221 
obtaining resolution, using restimer subroutine, 
1-220—1-221 
setting using settimer subroutine, 
1-—220—1-221 
times subroutine, 1-211—1-213 
timezone subroutine, 1-101—1-103 
tmpfile subroutine, 1-753 
tmpnam subroutine, 1-754—1-755 
tojhira subroutine, 1-285 
tojkata subroutine, 1-285 
tojlower subroutine, 1-285 
tojupper subroutine, 1-285 
toujis subroutine, 1-285 
trace channel, stopping a trace session for, using 
trcstop subroutine, 1-763 
trace data 
halting collection of, using trcoff subroutine, 
1-760 
starting the collection of, using trcon 
subroutine, 1-761 
trace link station activity, DLC, 3-40 


trace session 
recording 5 user-defined words, using trchkgt 
subroutine, 1-758—1-—759 
recording a data word 
using trcgen subroutine, 1-756 
using tregent subroutine, 1-756—1-—757 
recording a data word trace event, using trchklt 
subroutine, 1-758—1—759 
recording a hook word 
using tregen subroutine, 1-756—1—757 
using tregent subroutine, 1-756—1—757 
using trchkgt subroutine, 1-758—1—759 
using trchkl subroutine, 1-758—1—759 
using trchklt subroutine, 1-758—1—759 
using trchkt subroutine, 1-758 
recording a hook word plus 5 words, using 
trchkg subroutine, 1—758—1—759 
recording a timestamp 
using tregent subroutine, 1-756—1~—757 
using trchkgt subroutine, 1-758—1—759 
using trchklt subroutine, 1-758—1-—759 
using trchkt subroutine, 1-758 
recording a variable number of bytes of trace 
data 
using trcgen subroutine, 1-756 
using tregent subroutine, 1-756—1—757 
recording data word trace event, using trchkl 
subroutine, 1-758—1-—759 
starting, using trestart subroutine, 1-762 - 
transfer key—value pair from server to client, yp_all, 
5-131 
translate names to addresses, using knlist 
subroutine, 1-297—1-—298 
translation . 
AIX to EBCDIC, using NLxout subroutine, 
1-484 
character strings 
NLescstr subroutine, 1-466—1-—467 
NLflatstr subroutine, 1-466—1—467 
NLunescestr subroutine, 1-466—1—467 
EBCDIC to AIX, using NLxin subroutine, 
1—-482—1-483 
keysymbol to string, using IMAIXMapping 
subroutine, 1-250 
pair of keysymbol and state, using 
IMSimpleMapping subroutine, 1-276 
state to string, using IMAIXMapping subroutine, 
1-250 
translation table, initializing, using NLxstart 
subroutine, 1-485 
trcgen subroutine, 1-756—1-—757 
trcgent subroutine, 1-756—1-—757 
trchk subroutine, 1-758—1—759 
trchkg subroutine, 1-758—1-—759 
trchkgt subroutine, 1-758—1-—759 
trchkl subroutine, 1-758—1-—759 
trchkit subroutine, 1-758—1—759 
trchkt subroutine, 1-758 
trcoff subroutine, 1-760 
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trcon subroutine, 1-761 

trestart subroutine, 1-762 

trestop subroutine, 1-763 

trunc subroutine, 1-141—1-143 

truncate subroutine, 1-764—1~765 

tty locking functions, controlling, 1-768 

ttylock subroutine, 1-768—1-—769 

ttylocked subroutine, 1—-768—1-—769 

ttyname subroutine, 1-770 

ttyslot subroutine, 1-771 

ttyunlock subroutine, 1-768—1-—769 

ttywait subroutine, 1-768—1-—769 

turn data notification on or off, HCON programming, 
2-46 

tzset subroutine, 1-101—1-103 


U 


ualarm subroutine, 1-190—1-192 
uitrunc subroutine, 1-141—1-143 
ujtojis subroutine, 1-292—1-—293 
ujtosj Subroutine, 1-292—1-293 
ulimit subroutine, 1-772—1-773 
umask subroutine, 1-774 
umount subroutine, 1-775—1-776 
umul_dbl subroutine, 1-5—1-6 
uname subroutine, 1-777—1-778 
unamex subroutine, 1-777—1-778 
ungetc subroutine, 1-779—1-—780 
ungetwc subroutine, 1-779 
unlink subroutine, 1-781—1-—782 
unload object file, 1-783 
unload subroutine, 1-783 
unordered subroutine, 1-82—1-83 
update file systems, using sync subroutine, 1-731 
update NIS map, yp_update, 5-144 
user 
accessing group information 
using getgroupattr subroutine, 
1—184— 1-187 
using IDtogroup subroutine, 1-184—1-187 
using nextgroup subroutine, 1-184—1-187 
using putgroupattr subroutine, 


1-184—1-187 
authenticating, using ckuserlD subroutine, 
1-78—1-79 


checking account validity, using ckuseracct 
subroutine, 1-80—1-—81 

closing the database, using enduserdb 
subroutine, 1-638—1—639 

gets process user ID, using getuidx subroutine, 
1-227 

getting effective ID, using geteuid subroutine, 
1-226 

getting real ID, using getuid subroutine, 1-226 

opens the database, using setuserdb 
subroutine, 1-638—1-639 

returning information 

using getuserattr subroutine, 
1-—229—1-234 
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using !Dtouser subroutine, 1-229—1-—234 
using nextuser subroutine, 1-229—1-234 
using putuserattr subroutine, 
1-229—1-234 
accessing group information, using 
putgroupattr subroutine, 1-616 
sets process IDs, using setuidx subroutine, 
1-636— 1-637 
setting process IDs 
using seteuid subroutine, 1-634—1-635 
using setreuid subroutine, 1-634—1-635 
using setruid subroutine, 1-634—1-635 
using setuid subroutine, 1-634— 1-635 
user information buffer, search, using getuinfo 
subroutine, 1-228 
user2netname subroutine, RPC, 5-87 
usleep subroutine, 1-487—1—488 
usrinfo subroutine, 1-784—1-—785 
ustat subroutine, 1-709—1-—710 
utime subroutine, 1-786—1-—787 
utimes subroutine, 1-786—1-—787 
utmp file, finding slot for current user, using ttyslot 
subroutine, 1-771 
utmpname subroutine, 1-237—1-—239 
uuid_$decode library routine, NCS, 4-47 
uuid_$encode library routine, NCS, 4-48 
uuid_$gen library routine, NCS, 4~49 
uvmount subroutine, 1-775—1-—776 


V 


val function, xgmon, 6-81 
valloc subroutine, 1-399—1-402 
varargs macros, 1—-788—1-—789 
varargs parameter list 
format and print, 1-481 
formatting for output, 1-794—1-795 
vfork subroutine, 1-147—1-149 
vfprint subroutine, 1-794—1-—795 
virtual circuit for X.25 
resynchronizing communications on, using 
x25_reset subroutine, 9-35 
returning configuration on a, using 
x25_circuit_query subroutine, 9-9—-9-10 
virtual file system 
get mount status, using mnictl subroutine, 
1-—423—1-424 
remove from file tree,.1-775 
vlimit subroutine, 1-208—1-210 
vmount subroutine, 1-790—1-—793 
vprint subroutine, 1-794—1-—795 
vsprint subroutine, 1—794—1-795 
vtimes subroutine, 1—211—1-213 


W 


WAIT LAF statement, HCON programming, 2-95 
wait subroutine, 1-796—1-798 

wait3 subroutine, 1-796—1-798 

waitpid subroutine, 1-796—1~—798 


watof subroutine, 1-819—1-820 
watol subroutine, 1-821—1-822 
wchar_t character, locating in a wide—character 
string, using wesrchr subroutine, 1-804 
wcescat subroutine, 1-799 
weschr subroutine, 1-799 
wescpm subroutine, 1-799 
wescpy subroutine, 1-799—1-—800 
weslen subroutine, 1-801 
wesncat subroutine, 1-802 
wesncemp subroutine, 1-802 
wesncpy subroutine, 1-802 
wespbrk subroutine, 1-803 
wesrchr subroutine, 1-804 
wesspn subroutine, 1-805 
westombs subroutine, 1-806 
wcswcs subroutine, 1-807 
wctomb subroutine, 1-808 
WHILE LAF statement, HCON programming, 2-97 
wide—character string, determining the number of 
characters, using wcslen subroutine, 1-801 
wide—characters 
appending, using wcsncat subroutine, 1-802 
appending copy, wcscat subroutine, 
1-—799—1-800 
comparing, using wcsncmp subroutine, 1-802 
comparing two wchar_t strings, wcscmp 
subroutine, 1-799 
computing number of wchar_t characters, 
wescspn subroutine, 1-799 
copying, using wcsncpy subroutine, 1-802 
copying contents of parameter, wcscpy 
subroutine, 1-799 
locating in a string, wcswcs subroutine, 1-807 
returning a pointer, wcschr subroutine, 1-799 
returning number, using wcsspn subroutine, 
1-805 
window_height function, xgmon, 6-82 
window_width function, xgmon, 6-83 
words _free function, xgmon, 6-84 
write subroutine, 1-809—1-—812 
extended parameters for, DLC, 3-75 
write subroutine for generic SNA, SNA, 7-83 
write subroutine for SNA Services/6000, SNA, 7-81 
write to a file, 1-809—1-812 
writev subroutine, 1-809—1-812 
writevx subroutine, 1-809—1-812 
writex subroutine, 1-809—1-812 
DLC, 3-77 
writex subroutine for SNA Services/6000, SNA, 7-85 
wsprintf subroutine, 1-813—1-814 
wsscanf subroutine, 1-815 
wstrcat subroutine, 1-816 
wsirchr subroutine, 1-816 
wstrcmp subroutine, 1-816 
wstrcpy subroutine, 1-816 
wstrcspn subroutine, 1-816 
wstrdup subroutine, 1-817 
wstrlen subroutine, 1-816 


wstrncat subroutine, 1-816 
wstrncmp subroutine, 1-816 
wstrncpy subroutine, 1-816 
wstrpbrk subroutine, 1-816 
wstrrchr subroutine, 1-816 
wstrspn subroutine, 1~-816 
wstrtod subroutine, 1-819—1-820 
wstrtok subroutine, 1-816 

wsirtol subroutine, 1-821—-1-822 
wstrtos subroutine, 1-463 


X 


X.25 adapter, returning configuration information on, 
using x25_device_query subroutine, 9-17—9-18 
X.25 Communications Library 
x25_ack subroutine, 9-3 
x25_call subroutine, 9~-4—9-5 
x25_call_accept subroutine, 9-6 
x25_call_clear_subroutine, 9-7 
x25_circuit_query subroutine, 9-9—-9-10 
x25_ctr_get subroutine, 9-11 
x25_ctr_remove subroutine, 9-12 
x25_ctr_test subroutine, 9-13 
x25_ctr_wait subroutine, 9-14—9-15 
x25_deafen subroutine, 9-16 
x25_device_query subroutine, 9-1 7—9-18 
x25_init subroutine, 9-19 
x25_interrupt subroutine, 9-20 
x25_link_connect subroutine, 9-21 
x25_link_disconnect subroutine, 9-22—9-23 
x25_link_monitor subroutine, 9-24—9-25 
x25_link_query subroutine, 9-26—-9-—27 
x25_link_statistics subroutine, 9-28—9-—29 
x25_listen subroutine, 9-30 
x25_pvc_alloc subroutine, 9-31 
x25_pvc_free subroutine, 9-32 
x25_receive subroutine, 9-33—9-34 
x25_reset subroutine, 9-35 
x25_reset_confirm subroutine, 9-36 
x25_send subroutine, 9-37 
x25_term subroutine, 9-38 
X.25 port 
connecting to the X.25 network, using 
x25_link_connect subroutine, 9-21 
controlling the monitoring of, using 
x25_link_monitor subroutine, 9-24—9-25 
disconnecting, using x25_link_disconnect 
subroutine, 9-22—9-—23 
requesting statistics for, using 
x25_link_statistics subroutine, 9-28—-9~29 
returning the current status of, using 
x25_link_query subroutine, 9-26—9-27 
terminating the X.25 API for a, using x25_term 
subroutine, 9-38 
x25_ack subroutine for X.25, 9-3 
x25_call subroutine for X.25, 9-4—9-5 
x25_call_accept subroutine for X.25, 9-6 
x25_call_clear subroutine for X.25, 9-7—-9-8 
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x25_circuit_query subroutine for X.25, 9-9—9-10 
x25_ctr_get subroutine for X.25, 9-11 
x25_ctr_remove subroutine for X.25, 9-12 
x25_ctr_test subroutine for X.25, 9-13 
x25_ctr_wait subroutine for X.25, 9-14—9-15 
x25_deafen subroutine for X.25, 9-16 
x25_device_query subroutine for X.25, 9-17—9-18 
x25_init subroutine for X.25, 9-19 
x25_interrupt subroutine for X.25, 9-20 
x25_link_connect subroutine for X.25, 9-21 
x25_link_disconnect subroutine for X.25, 
9—22—9~23 

x25_link_monitor subroutine for X.25, 9-24—9-—25 
x25_link_query subroutine for X.25, 9-26—9-27 
x25_link_statistics subroutine for X.25, 9-28—9-29 
x25_listen subroutine for X.25, 9-30 
x25_pvc_alloc subroutine for X.25, 9-31 
x25_pvc_free subroutine for X.25, 9-32 
x25_receive subroutine for X.25, 9-33-—9-34 
x25_reset subroutine for X.25, 9-35 
x25_reset_confirm subroutine for X.25, 9-36 
x25_send subroutine for X.25, 9-37 
x25_term subroutine for X.25, 9-38 
XDR macros 

xdr_destroy, 5-95 

xdr_inline, 5-101 

xdr_setpos, 5-112 
XDR subroutines 

xdr_array, 5-89 

xdr_bytes, 5-91 

xdr_char, 5-94 

xdr_double, 5-96 

xdr_enum, 5-97 

xdr_float, 5-98 

xdr_free, 5-99 

xdr_int, 5-102 

xdr_long, 5-103 

xdr_opaque, 5-104 

xdr_pointer, 5-108 

xdr_reference, 5-109 

xdr_short, 5-113 

xdr_string, 5-114 

xdr_u_char, 5-115 

xdr_u_int, 5-116 

xdr_u_long, 5-117 

xdr_u_short, 5-118 

xdr_union, 5~119 

xdr_vector, 5-120 

xdr_void, 5-121 

xdr_wrapstring, 5-122 

xdrmem_create, 5-123 

xdrrec_create, 5-124 

xdrrec_endofrecord, 5-125 

xdrrec_eof, 5-126 

xdrrec_skiprecord, 5-127 

xdrstdio_create, 5-128 
xdr_accepted_reply subroutine, RPC, 5-88 
xdr_array subroutine, XDR, 5-89 
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xdr_authunix_parms subroutine, RPC, 5-90 
xdr_bytes subroutine, XDR, 5-91 
xdr_callhdr subroutine, RPC, 5-92 
xdr_callmsg subroutine, RPC, 5-93 
xdr_char subroutine, XDR, 5-94 
xdr_destroy macro, XDR, 5-95 
xdr_double subroutine, XDR, 5-96 
xdr_enum subroutine, XDR, 5—97 
xdr_float subroutine, XDR, 5-98 

xdr_free subroutine, XDR, 5—99 

xdr_inline macro, XDR, 5-101 

xdr_int subroutine, XDR, 5-102 

xdr_long subroutine, XDR, 5-103 
xdr_opaque subroutine, XDR, 5-104 
xdr_opaque_auth subroutine, RPC, 5-105 
xdr_pmap subroutine, RPC, 5-106 
xdr_pmaplist subroutine, RPC, 5-107 
xdr_pointer subroutine, XDR, 5-108 
xdr_reference subroutine, XDR, 5-109 
xdr_rejected_reply subroutine, RPC, 5-110 
xdr_replymsg subroutine, RPC, 5-111 
xdr_setpos macro, XDR, 5-112 

xdr_short subroutine, XDR, 5-113 
xdr_string subroutine, XDR, 5-114 
xdr_u_char subroutine, XDR, 5-115 
xdr_u_int subroutine, XDR, 5-116 
xdr_u_long subroutine, XDR, 5-117 
xdr_u_short subroutine, XDR, 5-118 
xdr_union subroutine, XDR, 5-119 
xdr_vector subroutine, XDR, 5—120 
xdr_void subroutine, XDR, 5-121 
xdr_wrapstring subroutine, XDR, 5-122 
xdrmem_create subroutine, XDR, 5-123 
xdrrec_create subroutine, XDR, 5-124 
xdrrec_endofrecord subroutine, XDR, 5-125 
xdrrec_eof subroutine, XDR, 5-126 
xdrrec_skiprecord subroutine, XDR, 5-127 
xdrstdio_create subroutine, XDR, 5-128 
xid data received routine, 3-67 
xprt_register subroutine, RPC, 5-129 
xprt_unregister subroutine, RPC, 5—130 


Y 


yO subroutine, 1-50—1-—51 

y1 subroutine, 1-50—1-—51 

yn subroutine, 1-50—1—51 

yp _master subroutine, 5-138 
yp_all subroutine, 5-131 
yp_bind subroutine, 5-133 
yp_first subroutine, 5-135 
yp_get_default_domain subroutine, 5-137 
yp_match subroutine, 5-139 
yp_next subroutine, 5~140 
yp_order subroutine, 5-142 
yp_unbind subroutine, 5-143 
yp_update subroutine, 5-144 
yperr_string subroutine, 5-146 
ypprot_err subroutine, 5-147 
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